mcp-commerce-starter

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

It's ~1,100 lines of Node.js, and it's a real server, not a tutorial. It handles pagination over large order sets, idempotent fulfillment calls, structured errors the model can recover from, and read/write separation so an agent 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 part nobody publishes.

Tools

Analytics (read-only)

Products (read + write)

Orders (read-only)

Logistics (write — Delhivery API)

Related MCP server: Clind MCP Server

Architecture Notes

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

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

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

IST date handling: All date boundaries shifted for IST (UTC+5:30). A query for "today's orders" returns orders placed on the Indian calendar day, not the UTC 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 and either 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 own logistics 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 tools will return an error if called, but all other tools continue to work.

Related

• 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.