mcp-commerce-starter

An MCP server is how you hand an AI agent a real set of hands. This one exposesa Shopify commerce backend — orders, inventory, logistics, fulfillment — as ~22typed tools an agent can actually call, with the guardrails that keep it fromdoing something irreversible.

It's ~1,100 lines of Node.js, and it's a real server, not a tutorial. Ithandles pagination over large order sets, idempotent fulfillment calls,structured errors the model can recover from, and read/write separation so anagent can analyze freely but only mutate through explicit, narrow tools.

I'm shipping it as a starter because the gap between "MCP hello-world" and"MCP server you'd trust against a production backend" is exactly the partnobody publishes.

Tools

Analytics (read-only)

Tool	What it does
`get_monthly_sales`	Revenue, order count, AOV, COD/prepaid split for a month
`get_daily_sales`	Sales for a specific date
`get_monthly_trend`	Month-over-month trend table
`compare_months`	Side-by-side comparison of two months
`get_product_sales_by_month`	Per-product revenue breakdown
`get_store_stats`	Lifetime store stats

Products (read + write)

Tool	What it does
`get_all_products`	Full catalog with status, price, SEO fields
`get_product`	Single product by ID
`update_product_seo`	Update SEO meta title + description
`update_product_description`	Update product body HTML
`update_product_image_alt`	Update image alt text
`get_product_page_analytics`	Cross-references catalog with orders to flag low-converting products
`get_inventory_status`	Live inventory levels across all products

Orders (read-only)

Tool	What it does
`search_order`	Find order by name, phone, or email
`get_order`	Single order by ID
`get_order_tracking`	AWB + tracking status for an order
`get_recent_orders`	Last N orders
`get_cod_orders`	COD orders for a date range
`get_unfulfilled_orders`	Pending fulfillment queue

Logistics (write — Delhivery API)

Tool	What it does
`create_delhivery_shipment`	Book a forward shipment (creates AWB)
`create_delhivery_reverse_pickup`	Book a return pickup from customer
`fulfill_shopify_order`	Mark order fulfilled in Shopify with tracking

Architecture Notes

Auth: Uses Shopify Partner app OAuth flow (client_credentials) — access tokenscached in memory, auto-refreshed before expiry. No session tokens stored to disk.

Pagination: Large order sets paginated transparently via Shopify's cursor-basedpage_info system. Callers get complete data without managing cursors.

Read/write separation: Analytics, product reads, and order reads are allread-only. Only update_*, create_*, and fulfill_* tools mutate state.This separation is enforced at the tool description level — the model is toldexplicitly which tools are safe to call freely vs. which require confirmation.

IST date handling: All date boundaries shifted for IST (UTC+5:30). A queryfor "today's orders" returns orders placed on the Indian calendar day, not theUTC day.

Structured errors: Tool errors return a JSON object with error, code,and detail fields — not raw stack traces. The model can parse the error andeither retry with corrected inputs or explain the failure to the user.

Setup

1. Clone and install

git clone https://github.com/singhjitesh889-blip/mcp-commerce-starter.git
cd mcp-commerce-starter
npm install

2. Configure environment

cp .env.example .env
# Fill in your Shopify credentials and seller details

3. Create a Shopify Partner app

You need a Shopify Partner app with the following scopes:

read_products, write_products
read_orders
read_inventory

Get your client_id and client_secret from the Shopify Partner Dashboard.

4. Wire into Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "commerce": {
      "command": "node",
      "args": ["/path/to/mcp-commerce-starter/index.js"],
      "env": {
        "SHOPIFY_SHOP": "https://your-store.myshopify.com",
        "SHOPIFY_CLIENT_ID": "your_client_id",
        "SHOPIFY_CLIENT_SECRET": "your_client_secret",
        "SELLER_NAME": "Your Business",
        "SELLER_CITY": "Your City",
        "SELLER_STATE": "Your State",
        "RETURN_PIN": "000000",
        "RETURN_PHONE": "9999999999",
        "RETURN_ADDRESS": "Your return address",
        "RETURN_CITY": "Your City",
        "RETURN_STATE": "Your State"
      }
    }
  }
}

5. Test

> what were my sales last month?
> show me unfulfilled orders
> search for order #1234

The Logistics Tools

The Delhivery integration (create_delhivery_shipment, create_delhivery_reverse_pickup)requires a Delhivery API account. These are India-specific — swap in your ownlogistics provider's API for other markets. The tool interface stays the same;the API call underneath is what changes.

If you don't use Delhivery, leave DELHIVERY_API_TOKEN unset — the toolswill return an error if called, but all other tools continue to work.

claude-code-knowledge-architecture — the methodology that makes this server useful in sustained AI-assisted operations.
mcp-seo-starter — companion MCP server for search performance data.

mcp-commerce-starter