shopify-multistore-mcp

An MCP server for working across multiple Shopify stores (multi-client dev work) through the Admin GraphQL API. Every tool takes a store argument that routes the call to the right client store, so one connector covers all your stores.

Designed to sit alongside Shopify's official tooling, not replace it:

Layer	What it does	You build it?
Shopify AI Toolkit / Dev MCP	Theme, apps, Functions, extensions, docs + GraphQL validation	No — install it
Shopify CLI	theme dev, app dev, Functions deploy (per-store auth)	No — install it
This server	Conversational Admin API read/write across stores, with a production write-gate	Yes — this repo

What's here (first milestone)

Tools exposed to Claude:

• list_stores — list configured stores (alias, domain, env, API version)
• shop_info — identity/plan for a store (great connectivity check)
• get_products — list/search products (Shopify search syntax)
• get_orders — list/search recent orders
• graphql — raw Admin GraphQL escape hatch (query or mutation)

The production write-gate

Each store is tagged env: "production" or env: "dev".

• Mutations against a dev store run freely.
• Mutations against a production store are blocked unless the call passes confirm: true. The model must inspect what will change, then explicitly confirm.

This protects live client data while keeping dev stores frictionless.

Setup

1. Install dependencies & build

npm install
npm run build

This machine's Node lives in Laragon: D:\Ahsan\laragon\bin\nodejs\node-v22\. Either add that folder to your PATH, or use the full path to node.exe / npm.cmd (the Claude config below uses the full path so it works regardless of PATH).

2. Create your store registry

Copy the example and fill in real values:

cp stores.example.json stores.json

stores.json is gitignored — never commit real tokens.

{
  "defaultApiVersion": "2026-07",
  "stores": {
    "acme-live": {
      "label": "Acme Corp (production)",
      "domain": "acme-corp.myshopify.com",
      "env": "production",
      "adminToken": "shpat_xxx"
    },
    "acme-dev": {
      "label": "Acme dev store",
      "domain": "acme-corp-dev.myshopify.com",
      "env": "dev",
      "adminToken": "shpat_yyy"
    }
  }
}

• adminToken — inline the token, or use adminTokenEnv to read it from an environment variable (e.g. "adminTokenEnv": "ACME_TOKEN") so secrets stay out of the file.
• apiVersion — optional per-store override of defaultApiVersion.

3. Get an Admin API access token per store

In each store's admin: Settings → Apps and sales channels → Develop apps → Create an app → Configure Admin API scopes, then install and copy the Admin API access token (shpat_…).

Grant only the scopes you need, e.g. read_products, write_products, read_orders, read_content, write_content, read_themes, write_themes, read_metaobjects, write_metaobjects.

Connect it to Claude

Add to your MCP config (Claude Desktop claude_desktop_config.json, or Claude Code .mcp.json). This wires all three layers — official Dev MCP + this multi-store server:

{
  "mcpServers": {
    "shopify-dev": {
      "command": "npx",
      "args": ["-y", "@shopify/dev-mcp@latest"]
    },
    "shopify-multistore": {
      "command": "D:\\Ahsan\\laragon\\bin\\nodejs\\node-v22\\node.exe",
      "args": ["D:\\Ahsan\\workstuff\\source\\shopify-mcp-connector\\dist\\index.js"],
      "env": {
        "STORES_CONFIG": "D:\\Ahsan\\workstuff\\source\\shopify-mcp-connector\\stores.json"
      }
    }
  }
}

For the theme/app/Functions dev workflow, also install the official Shopify AI Toolkit Claude Code plugin and the Shopify CLI.

Config resolution

The server finds stores.json in this order:

1. STORES_CONFIG env var (recommended — see config above)
2. ./stores.json relative to the working directory

Usage examples (things to ask Claude)

• "List my configured stores."
• "Show active products from vendor Acme in acme-dev."
• "How many unfulfilled orders does acme-live have this week?"
• "Add a metafield custom.care_instructions to product X in acme-dev." (raw graphql, dev store — runs)
• "Update the price of variant Y in acme-live." (raw graphql, production — asks you to confirm first)

Roadmap (next milestones)

• Dedicated write tools (create/update products, metafields, pages) with the same gate
• Metafield/metaobject read + write helpers
• Theme asset read/write, page/blog content tools
• Bulk operation helpers (bulk query + bulkOperationRunMutation)
• Optional remote/HTTP deployment if the connector needs to be shared with a team

Development

npm run dev        # tsc --watch
npm run typecheck  # type-check without emitting
npm run build      # compile to dist/

Project layout

src/
  index.ts    # MCP server entry (stdio)
  config.ts   # store registry loader + zod validation
  shopify.ts  # Admin GraphQL client + production write-gate
  tools.ts    # tool definitions
stores.example.json  # template — copy to stores.json (gitignored)