openshop-shopify-mcp

Shopify Admin MCP server — 146 tools + 164 report templates for Claude, ChatGPT, Cursor, and any MCP client.

GitHub: github.com/openshopdev/openshop

Connect any AI assistant to your Shopify store. Full Admin API coverage: products, orders, customers, inventory, discounts, analytics (ShopifyQL), fulfillment, themes, content, gift cards, returns, subscriptions, and more.

Quick Start

npx openshop-shopify-mcp

Setup

1. Create a Shopify App

1. Go to Shopify Dev Dashboard → Create app
2. Go to Configuration → API access scopes
3. Select all scopes (the MCP needs broad access to manage your store). Quick way to check all:
   • Open browser DevTools (F12) → Console → paste:

   document.querySelectorAll('[data-app-module--app-access-target="scopesCheckbox"]').forEach(cb => { if (!cb.checked) cb.click(); });

4. Save and Install the app on your store
5. Copy Client ID and Client Secret

2. Set Environment Variables

SHOPIFY_STORE_DOMAIN=mystore.myshopify.com
SHOPIFY_CLIENT_ID=your_client_id
SHOPIFY_CLIENT_SECRET=your_client_secret

Connect to Your AI Client

Claude Desktop

Add to your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "openshop": {
      "command": "npx",
      "args": ["-y", "openshop-shopify-mcp"],
      "env": {
        "SHOPIFY_STORE_DOMAIN": "mystore.myshopify.com",
        "SHOPIFY_CLIENT_ID": "your_client_id",
        "SHOPIFY_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Claude Code (CLI)

Option A — .mcp.json (recommended, shareable with your team):

Add a .mcp.json file to your project root:

{
  "mcpServers": {
    "openshop": {
      "command": "npx",
      "args": ["-y", "openshop-shopify-mcp"],
      "env": {
        "SHOPIFY_STORE_DOMAIN": "mystore.myshopify.com",
        "SHOPIFY_CLIENT_ID": "your_client_id",
        "SHOPIFY_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Option B — CLI commands:

claude mcp add openshop -- npx -y openshop-shopify-mcp

# Set credentials
claude mcp set-env openshop SHOPIFY_STORE_DOMAIN mystore.myshopify.com
claude mcp set-env openshop SHOPIFY_CLIENT_ID your_client_id
claude mcp set-env openshop SHOPIFY_CLIENT_SECRET your_client_secret

ChatGPT Desktop

ChatGPT supports MCP servers via its desktop app. Add to your ChatGPT config:

• macOS: ~/Library/Application Support/com.openai.chat/mcp.json
• Windows: %APPDATA%\com.openai.chat\mcp.json

{
  "mcpServers": {
    "openshop": {
      "command": "npx",
      "args": ["-y", "openshop-shopify-mcp"],
      "env": {
        "SHOPIFY_STORE_DOMAIN": "mystore.myshopify.com",
        "SHOPIFY_CLIENT_ID": "your_client_id",
        "SHOPIFY_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Cursor

Open Cursor Settings → MCP → Add new server:

{
  "mcpServers": {
    "openshop": {
      "command": "npx",
      "args": ["-y", "openshop-shopify-mcp"],
      "env": {
        "SHOPIFY_STORE_DOMAIN": "mystore.myshopify.com",
        "SHOPIFY_CLIENT_ID": "your_client_id",
        "SHOPIFY_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "openshop": {
      "command": "npx",
      "args": ["-y", "openshop-shopify-mcp"],
      "env": {
        "SHOPIFY_STORE_DOMAIN": "mystore.myshopify.com",
        "SHOPIFY_CLIENT_ID": "your_client_id",
        "SHOPIFY_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Any MCP Client

The server uses stdio transport — any MCP-compatible client can connect:

# Start the server (communicates via stdin/stdout)
SHOPIFY_STORE_DOMAIN=mystore.myshopify.com \
SHOPIFY_CLIENT_ID=your_client_id \
SHOPIFY_CLIENT_SECRET=your_client_secret \
npx openshop-shopify-mcp

146 Tools

| Category | Tools | Examples | |----------|-------|---------| | Products | 14 | list, get, create, update, delete, duplicate, status, variants, media, options, collections CRUD, add/remove products | | Orders | 19 | list, get, create, update, close, cancel, mark paid, refund, tags add/remove, draft orders full CRUD, order editing | | Customers | 10 | list, get, create, update, delete, tags, send invite, update address, merge, segment query | | Inventory | 5 | levels, locations, set/adjust quantities, transfer between locations | | Analytics | 8 | ShopifyQL (30+ columns incl. returning_customer_rate, gross_margin, rfm_group), 164 report templates, customer retention, top products, inventory report | | Discounts | 9 | list, get, create code/automatic/BXGY/free shipping, update code/automatic, delete | | Gift Cards | 5 | list, get, create, credit, deactivate | | Returns | 5 | list, get, create, approve, close | | Content | 7 | pages, blogs create, articles, redirects | | Themes | 5 | list, read/update/delete assets, publish | | Fulfillment | 6 | list, create, tracking, cancel, hold, release | | Metafields | 3 | get, set, delete | | Metaobjects | 4 | definitions, list, manage | | Store Credit | 4 | balance, list, credit, debit | | Companies | 4 | B2B list, get, create, update | | Files | 3 | list, upload, delete | | Webhooks | 3 | list, subscribe, unsubscribe | | Bulk Ops | 3 | export, import, status | | Publications | 2 | list, publish/unpublish | | Order Editing | 3 | begin, add/change items, commit | | Abandoned Checkouts | 2 | list, get | | Segments | 4 | list, get, create, query customers | | Subscriptions | 4 | selling plans, contracts, pause/activate/cancel | | Markets | 4 | get, create, update, delete | | Translations | 3 | list, register, remove | | Menus | 3 | list, get, manage | | Price Lists | 4 | list, get, create, add prices | | Store | 5 | info, locations, markets, policies, shipping profiles | | GraphQL | 1 | raw escape hatch |

Example Prompts

Once connected, ask your AI assistant things like:

• "Show me today's orders"
• "What's my returning customer rate?"
• "Create a 20% discount code SUMMER20"
• "Find customers who haven't ordered in 90 days"
• "What's my gross margin trend this year?"
• "Fulfill order #1234 with tracking number 9400111899..."
• "Create a buy-2-get-1-free discount"
• "Put order #5678 on hold — address needs verification"
• "Show me the RFM customer analysis report"
• "What reports are available for inventory?"
• "Compare this month's sales to last month"
• "Give me a full retention health check"

Built by Shopify Developers

This isn't a weekend wrapper around a few API calls. It's built by developers who ship Shopify apps professionally and understand the platform deeply:

• 164 built-in report templates — extracted from Shopify's own analytics dashboard. Search "conversion rate" and get the exact ShopifyQL query Shopify uses internally.
• ShopifyQL mastery — we know returning_customer_rate, gross_margin, rfm_group, amount_spent_per_customer exist as columns (most MCP tools don't). 30+ verified metrics and dimensions.
• Customer segment queries — segments_query_customers uses Shopify's segment query language to find customers: number_of_orders > 1 AND total_spent > 500000. Returns real customer data, not just counts.
• API 2026-04 battle-tested — we found and fixed 27 breaking changes in the latest API version that no other package knows about. @idempotent directive on inventory mutations, context field on discounts, productOptionsCreate replacing ProductInput.options, and more.
• Schema-fix fallback — when Shopify changes their API, our tools auto-detect the error, introspect the live schema, fix the query, and retry. Zero downtime.
• Bulk Operations API — bulk_export and bulk_import use Shopify's async bulk API for millions of records without throttling. Other tools loop 10k API calls and get rate-limited.
• All 4 discount types — percentage, fixed amount, free shipping, Buy X Get Y. With minimum requirements, product/collection targeting, per-customer limits. Other MCP tools have 0-1 discount tools.
• Full order lifecycle — create orders (not just drafts), fulfill with tracking, hold/release fulfillment, edit orders, refund, cancel. Other tools stop at list + get.

Safety

• Destructive tools (delete, cancel, refund) require confirmed: true
• The AI must explicitly confirm before executing destructive actions
• All mutations are logged and traceable via Shopify's audit trail

Auth Methods

Dev Dashboard (recommended): Client credentials with auto-refresh (24h tokens).

SHOPIFY_CLIENT_ID=your_client_id
SHOPIFY_CLIENT_SECRET=your_client_secret

Static token (legacy):

SHOPIFY_ACCESS_TOKEN=shpat_xxxxx

Works on all Shopify plans (Basic $39+).

Testing

cd packages/admin-mcp

# Run all 116 integration tests (requires Shopify credentials)
bun test

# Run specific suite
bun test:mutations    # 63 mutation tests (create/verify/cleanup)
bun test:reads        # 53 read + mutation tests

Requires: SHOPIFY_STORE_DOMAIN, SHOPIFY_CLIENT_ID, SHOPIFY_CLIENT_SECRET

Use as a Library

import { loadConfig, ShopifyGraphQLClient, RateLimiter, TokenManager, registerAllTools } from "openshop-shopify-mcp";

const config = loadConfig();
const client = new ShopifyGraphQLClient(config, new TokenManager(config), new RateLimiter());

Contributing

Shopify's API surface is massive — 500+ GraphQL types, dozens of datasets, constantly evolving. We've covered the most important 95% of daily merchant workflows, but there's always more:

• Missing a tool? Open an issue describing the use case. Or PR a new tool — each tool is a single function in src/tools/.
• Know a ShopifyQL column we missed? The analytics-templates.json file has 164 report templates. If you find more, contribute them.
• Hit an API 2026-04 breaking change? Our schema-fix fallback catches most, but edge cases exist. Report them so everyone benefits.
• Built a Shopify app? You know the API better than most. Your expertise makes this tool better for every merchant.

# Add a new tool
# 1. Add your tool function to the appropriate file in src/tools/
# 2. Test it: bun test:merchant
# 3. PR it

License

MIT