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)

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