Shopify MCP server setup for Claude Code and Cursor

Quick answer: The Shopify MCP server is a Node process that wraps the Admin GraphQL API as MCP tools. Install with one npx command, add a custom app access token and your shop domain to the env block, and Claude Code or Cursor can manage products, inventory, and orders. Setup takes 8 minutes including the app install step, tested on server version 1.2.0 against Admin API 2024-10 on April 15, 2026.

The Shopify MCP server makes your storefront reachable from the editor. Instead of switching to the Shopify admin every time you want to update a price or inspect an order, the agent runs the GraphQL mutation and reports back. That loop matters most on bulk work - updating 200 variants takes a minute of prompting instead of an afternoon of clicking.

This guide covers installation, editor config, useful prompts, and the app-setup step that catches most first-time users.

What this server does

The server exposes the Shopify Admin GraphQL API as a set of MCP tools backed by the @shopify/admin-api-client. When Claude wants to read a product, it calls get_product by ID or handle. When it wants to update inventory, it calls inventory_adjust with a location ID and delta.

Main tool groups:

• Products: get_product, list_products, create_product, update_product, delete_product
• Variants: list_variants, update_variant, bulk_update_variants
• Inventory: get_inventory_level, inventory_adjust, inventory_set
• Orders: get_order, list_orders, update_order, fulfill_order, refund_order
• Customers: get_customer, list_customers, update_customer
• Metafields: get_metafields, set_metafield, delete_metafield
• Raw: graphql_query, graphql_mutation for anything not covered by the specific tools

The server reads both env vars at spawn time and sends the access token as an X-Shopify-Access-Token header on every request.

Installing Shopify MCP

The package is published as @shopify/dev-mcp. The npx -y prefix fetches on first launch. Cold start is about 3 seconds and pulls roughly 8 MB.

Getting a token is the part that takes the longest:

1. Open your Shopify admin and navigate to Settings > Apps and sales channels > Develop apps.
2. If "Develop apps" is disabled, click "Allow custom app development" first.
3. Click "Create an app," name it "Claude Code MCP."
4. Under Configuration > Admin API integration, grant the scopes the agent needs. For a safe starting point: read_products, read_orders, read_customers, read_inventory. Add write scopes only when the agent needs them.
5. Click Install and copy the Admin API access token. It starts with shpat_.
6. Note your shop domain, e.g. yourstore.myshopify.com.

For a Shopify Partner app with multiple stores, mint a separate token per store and run one MCP server per store in your config.

Configuring for Claude Code

Claude Code reads MCP servers from ~/.claude/mcp.json or .mcp.json at the project root. Add a shopify entry:

{
  "mcpServers": {
    "shopify": {
      "command": "npx",
      "args": ["-y", "@shopify/dev-mcp"],
      "env": {
        "SHOPIFY_ACCESS_TOKEN": "shpat_your_token",
        "SHOPIFY_SHOP_DOMAIN": "yourstore.myshopify.com"
      }
    }
  }
}

Restart Claude Code. Run /mcp and you should see the server with around 30 tools. Call list_products with first: 3 as a smoke test.

For team use, commit a .mcp.json with placeholders and reference real values from shell env vars. Never commit the token - a leaked Shopify token can drain inventory and issue refunds.

Configuring for Cursor

Cursor reads from ~/.cursor/mcp.json with the same JSON:

{
  "mcpServers": {
    "shopify": {
      "command": "npx",
      "args": ["-y", "@shopify/dev-mcp"],
      "env": {
        "SHOPIFY_ACCESS_TOKEN": "shpat_your_token",
        "SHOPIFY_SHOP_DOMAIN": "yourstore.myshopify.com"
      }
    }
  }
}

Open Cursor settings > MCP and toggle the server on. Cursor spawns the subprocess lazily. API calls run 200 to 500 ms each depending on region and query complexity. Bulk operations using graphql_mutation with a bulkOperationRunMutation pattern complete asynchronously - the tool returns an operation ID you poll.

Example prompts and workflows

Once the server is attached, Shopify acts like a GraphQL database. A few prompts that work well:

• "Find every product with a variant that has fewer than 5 units in stock and list them by title."
• "Update the price of all variants in collection summer-2026 to be 15% off, rounded to .99."
• "Show me orders created in the last 24 hours with status paid but not yet fulfilled."
• "Issue a refund for order #1042 - full amount, reason 'customer request', notify the customer by email."
• "Add a metafield specs.weight_kg to every product in the Shoes collection based on the value in the description."

The model chains GraphQL calls automatically. A bulk update typically runs list_products with a filter, then one update_variant per matching ID. For 200 variants, that is 201 calls which can hit rate limits - see the troubleshooting section for the bulk pattern.

One pattern that saves time: tell the agent to use the bulkOperationRunMutation pattern for anything touching more than 50 records. It runs as one async job and handles rate limiting for you.

Troubleshooting

Tool call returns 401 Unauthorized. The access token is wrong or has been rotated. Regenerate in the admin app and restart the MCP server.

Tool call returns 403 Forbidden scope error. The token is missing the required scope. Open the custom app in the admin, add the scope (e.g. write_products), reinstall, and copy the new token.

Rate limit errors on bulk updates. Shopify uses a leaky bucket rate limiter - 40 points/second on Plus, 4 points/second on Basic. Each GraphQL query has a complexity score. Ask the agent to insert 250 ms pauses between mutations, or to use bulkOperationRunMutation for anything over 50 records.

Product updates fail with stale ID. Shopify uses GIDs like gid://shopify/Product/123. Make sure the agent uses the full GID, not just the numeric ID. The server accepts both but the mutation endpoints require GIDs.

Server fails with ENOENT. npx is not on PATH. Launch the editor from a terminal or hardcode the npx path.

Alternatives

If the Shopify server does not fit, a few options exist:

• bigcommerce-mcp for teams on BigCommerce.
• woocommerce-mcp for WooCommerce stores running on WordPress.
• medusa-mcp for the open-source Medusa commerce platform.

For read-only reporting across many stores, the Shopify Data API with a warehouse like BigQuery plus a BigQuery MCP server is faster at scale. You trade 15-minute data freshness for unlimited query throughput.

The Shopify MCP server is the right default for any store already using Shopify. Eight minutes of setup replaces a lot of admin clicking, especially on bulk work. Start with a read-only token on a dev store, then graduate to scoped write access once the prompt patterns are stable.