shopify-inventory-mcp — Deterministic Inventory Forecasts for Any AI Assistant

Open-Source (MIT) | Local stdio MCP | Shopify Admin API (BYOK) | Not affiliated with Shopify

Status: v0 — deterministic forecast math + Shopify read layer + four stdio MCP tools. Bring your own store credentials. Numbers come from pure functions with fixture tests; the model only explains them.

1. Overview

Merchants ask AI assistants “what will I run out of?” Assistants can read inventory, but guessed reorder numbers are dangerous. This read-only MCP server computes weighted moving average demand, days of cover, stockout date, and reorder point from your Shopify data and returns structured JSON the model can explain — not invent.

Why BYOK: you run it locally with your own credentials. The token stays on your machine; tool results are still sent to the model provider by your MCP client, so treat product titles/notes as leaving via that channel.

Official Shopify MCP (UCP) covers storefront/cart/checkout — not Admin inventory forecasting. That’s the gap this fills.

This is deterministic forecasting (weighted moving averages + safety stock), not machine-learning / “AI forecasting.”

Related MCP server: shopify-mcp-server

2. Tools (v0)

v0 lead times are store-wide (env or tool param). Per-SKU config is v1.

3. How the numbers work (example)

SKU X: 150 in stock · demand 8/day · lead time 21 days → cover 18.75 → at risk; safety stock ≈ 22.7; reorder point ≈ 190.7.

Same formulas as Agent Forecast (forecasting.js). Defaults: WMA 4 / reorder WMA 14 / z=1.65 / lead 21d. Multi-location: sum available.

4. Setup (credentials)

Shopify no longer allows creating new admin-created custom apps. Use one of:

A. Dev Dashboard app (recommended for new setups)

1. Open the Dev Dashboard → Create app.

2. Create a version with App URL https://shopify.dev/apps/default-app-home (fine for API-only) and scopes:

   • read_inventory, read_locations, read_orders, read_products

3. Release the version, then Install on your store.

4. App settings → copy Client ID and Client secret.

5. Copy .env.example → .env and set:

SHOPIFY_STORE_DOMAIN=your-store.myshopify.com
SHOPIFY_CLIENT_ID=...
SHOPIFY_CLIENT_SECRET=...
# optional: LEAD_TIME_DAYS=21

Tokens from the client-credentials grant last ~24 hours; this server refreshes them automatically.

B. Existing admin-created custom app (legacy)

If you already have one: Apps → Develop apps → [app] → API credentials → Admin API access token. Set SHOPIFY_ADMIN_ACCESS_TOKEN instead of client ID/secret.

Order history note

read_orders only returns orders from the last 60 days. Thin history → weak forecasts. Extending further needs read_all_orders (protected access) — optional later, not required for v0.

5. Local development quickstart

Prerequisites: Node.js ≥ 20, npm, a Shopify store with the scopes above.

git clone https://github.com/arsalan-arshad/shopify-inventory-mcp.git
cd shopify-inventory-mcp
cp .env.example .env   # then fill in credentials
npm install
npm test
npm run build
npm start              # stdio MCP server (for clients that spawn it)

Or after build: npx shopify-inventory-mcp (uses the bin entry).

6. MCP client config

Replace /absolute/path/to/shopify-inventory-mcp with the real clone path on your machine (must point at dist/server.js after npm run build). Prefer putting secrets in the client env block or a local .env loaded by your process manager — never commit them.

Cursor

Add to Cursor MCP settings (.cursor/mcp.json in the project, or your global Cursor MCP config):

{
  "mcpServers": {
    "shopify-inventory": {
      "command": "node",
      "args": ["/absolute/path/to/shopify-inventory-mcp/dist/server.js"],
      "env": {
        "SHOPIFY_STORE_DOMAIN": "your-store.myshopify.com",
        "SHOPIFY_CLIENT_ID": "your-client-id",
        "SHOPIFY_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Legacy static token (if you have one): set SHOPIFY_ADMIN_ACCESS_TOKEN instead of client ID/secret.

Claude Desktop

Edit Claude Desktop’s MCP config (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "shopify-inventory": {
      "command": "node",
      "args": ["/absolute/path/to/shopify-inventory-mcp/dist/server.js"],
      "env": {
        "SHOPIFY_STORE_DOMAIN": "your-store.myshopify.com",
        "SHOPIFY_CLIENT_ID": "your-client-id",
        "SHOPIFY_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Restart Cursor / Claude Desktop after saving.

7. Example prompts

Once the server is connected, try:

• “Which SKUs am I most at risk of stocking out of in the next three weeks?”

• “Show me the forecast for SKU ABC-123 — daily demand, days of cover, and projected stockout date.”

• “What’s the reorder point and safety stock for SKU ABC-123 with a 14-day lead time?”

• “Explain how you calculated the forecast for SKU ABC-123 — which window and formulas?”

• “List at-risk SKUs, limit 20, assuming a 30-day lead time.”

The assistant should call the MCP tools (list_at_risk_skus, get_sku_forecast, get_reorder_suggestion, explain_forecast_inputs) rather than inventing numbers.

8. Verification & test suite

npm test          # vitest — math fixtures + Shopify layer unit tests
npm run build     # tsc → dist/

CI runs the same on every push/PR to main. A live end-to-end check against a real store still needs your credentials (not automated in CI).

9. Architecture

src/
  forecast/     # pure math (WMA, days of cover, reorder point) — no I/O
  shopify/      # BYOK Admin GraphQL read layer
  tools/        # schemas + handlers
  server.ts     # stdio MCP entry (bin)

flowchart LR
    C["MCP client"] -->|stdio| S["MCP server"]
    S --> F["Pure forecast functions"]
    S --> A["Shopify Admin GraphQL\nBYOK read-only"]

10. Roadmap

• v0: four tools, local stdio, store-wide lead time, docs, public GitHub repo

• v1: per-SKU config, CSV export, Reorder Brain tools

• Later: hosted tier, directory listing, Salesforce pipeline, bulk ops / read_all_orders

11. Contributing & Security

See CONTRIBUTING.md and SECURITY.md. Contact: arsalanarshad.dev@gmail.com.

12. License

MIT — see LICENSE. Not affiliated with Shopify Inc.