Shopify Dev MCP Install Guide: Setup in Claude Code

Quick win: The Shopify Dev MCP is a local stdio MCP server that gives Claude Code live access to Shopify's documentation and schema validation. No developer app. No OAuth. No credentials. Three commands:

# 1. Register and install
claude mcp add --transport stdio shopify-dev-mcp -- npx -y @shopify/dev-mcp@latest
 
# 2. Restart Claude Code, then verify
# 3. Ask: "What's the current GraphQL Admin mutation for productCreate?"

If Claude calls a tool instead of guessing from training data, the shopify dev mcp install worked.

The npm package is @shopify/dev-mcp, currently at v1.13.0 (published April 29, 2026). The schema bundle tracks the live Shopify Admin and Storefront APIs within days. This guide covers the standalone shopify mcp server setup for operators who want just the validation surface inside Claude Code, without the full AI Toolkit plugin.

What the Shopify Dev MCP Actually Does

The Dev MCP server is the validation and documentation half of the Shopify AI Toolkit, packaged as a single npm CLI you can wire to any MCP-compatible client. It does four things, and only four things:

1. Searches Shopify's developer documentation in real time. Ask "how do I create a discount with the GraphQL Admin API in 2026?" and Claude pulls the current docs page instead of hallucinating an outdated mutation.
2. Validates GraphQL queries against the live Admin and Storefront schemas. Paste any mutation, Claude tells you exactly which fields are wrong before you ever fire an HTTP request.
3. Validates Liquid templates against the theme schema. Catches missing variables and undefined filters before they hit your storefront.
4. Validates UI extension and Shopify Functions code against the current platform contracts.

Critically, none of this touches a real store. The Dev MCP server runs entirely on your machine, talks to Shopify's public docs and schema files, and never asks for credentials. If you also want Claude to mutate live data (bulk product updates, inventory adjustments, theme deploys), that's the Shopify CLI surface, which is a separate authenticated install. The Dev MCP server is the safe, read-only entry point. Most operators only ever need this. For protocol context on what MCP servers are and why they matter, our MCP basics guide is the primer.

The Shopify AI Toolkit pillar covers every component end to end. This page is the Dev MCP slice.

Prerequisites

Three things, all light:

• Node.js 18 or higher. Run node --version to verify. The package uses npx to fetch and run on demand, so a stale Node install is the most common cause of a "command not found" the first time you try.
• Claude Code installed and working in your terminal. If you don't have it yet, our installation guide covers Windows, macOS, and Linux.
• A working terminal. That's it. You do not need a Shopify Partner account, a development store, or a Shopify CLI install for the Dev MCP itself. You only need Shopify credentials when you graduate from "ask Claude about my code" to "let Claude run mutations against my store", and that's a separate flow.

If you plan to use the validation surface against proprietary client work, jump to the OPT_OUT_INSTRUMENTATION note in the Errors section before your first run. Validation payloads otherwise ship to Shopify for instrumentation by default.

Install Methods (Pick One)

Method 1: Claude Code via claude mcp add

The recommended standalone path, taken straight from Shopify's official docs:

claude mcp add --transport stdio shopify-dev-mcp -- npx -y @shopify/dev-mcp@latest

The --transport stdio flag is required. Stdio means Claude spawns the MCP server as a local subprocess, no port, no public surface. The -y on npx skips the interactive prompt the first time the package downloads.

Restart Claude Code if your active session doesn't pick the server up immediately. That's the entire shopify mcp install for Claude Code, manual edition.

Method 2: Claude Code via the Plugin (if you want everything)

If you want the full AI Toolkit instead of just the Dev MCP, the Shopify AI Toolkit pillar covers the plugin install. Choose Method 1 if you want a pinnable, CI-friendly, validation-only surface; choose the plugin if you want hands-off schema freshness and the full agent skill set.

Method 3: Cursor

Add this to your Cursor mcp.json:

{
  "mcpServers": {
    "shopify-dev-mcp": {
      "command": "npx",
      "args": ["-y", "@shopify/dev-mcp@latest"]
    }
  }
}

If you're new to MCP in Cursor, our Cursor MCP setup walkthrough covers the full config-file workflow.

Method 4: VS Code

VS Code uses a slightly different schema in its user-level config:

{
  "servers": {
    "shopify-dev-mcp": {
      "command": "npx",
      "args": ["-y", "@shopify/dev-mcp@latest"]
    }
  }
}

Note the top-level key is servers, not mcpServers.

Method 5: Codex CLI (TOML)

[mcp_servers.shopify-dev-mcp]
command = "npx"
args = ["-y", "@shopify/dev-mcp@latest"]

Drop that in ~/.codex/config.toml.

Verify Your Install Is Working

The cleanest verification for any shopify mcp setup: ask Claude a question that requires live docs. If the Dev MCP is wired correctly, Claude calls a tool; if it isn't, Claude makes something up from training data.

In a fresh Claude Code session, paste:

What's the current GraphQL Admin API mutation for creating a product with multiple variants in 2026, and what scopes does it require?

Two outcomes:

• Working install. You'll see Claude invoke a tool call (the docs search). The reply will cite specific field names from the live schema (like productCreate with the ProductInput type) and the exact scope (write_products). That's the Dev MCP doing its job.
• Broken install. Claude answers from memory with no tool invocation. The mutation might be close, but the Admin API moves fast and "close" loses you an afternoon when the field name changed. Restart Claude Code, run claude mcp list to confirm shopify-dev-mcp is registered, and check node --version is 18 or higher.

A second sanity check, if you want a paste-test: ask Claude to validate a deliberately broken GraphQL mutation. Something like mutation { productCreate(input: {titel: "Test"}) { product { id } } }. The misspelled titel should come back as a schema error from the Dev MCP, not a generic "looks fine" from Claude.

Common Shopify Dev MCP Install Errors

Four errors cover roughly 90% of the failed installs we've seen.

1. npx: command not found or node: command not found. Your Node install isn't on PATH, or you're below 18. Run node --version. If it's missing or below 18, install or upgrade Node first. On Windows, this is also the most common symptom of running the install in a stale terminal that hasn't picked up a fresh Node install.

2. spawn npx ENOENT or subprocess hangs on Windows. Stdio transport on Windows occasionally fails when the terminal can't keep the subprocess alive. The fix from Shopify's docs is to switch to a literal cmd /c wrapper for the command field in mcp.json (Cursor) or to relaunch Claude Code from a fresh PowerShell or Windows Terminal session. WSL2 is the most reliable Windows surface and avoids the issue entirely.

3. Server starts but Claude won't call its tools. Restart Claude Code. The MCP server is registered at startup, and an active session doesn't always notice the new entry. If a restart doesn't fix it, run:

claude mcp list

Confirm shopify-dev-mcp appears in the output. If it's missing, the install command silently failed -- re-run Method 1 from the Install Methods section above (usually a path or permission issue on Windows).

4. Validation payloads sent to Shopify and you needed them not to be. By default the Dev MCP transmits validation payloads to Shopify for instrumentation. If you handle proprietary schemas or NDA work, set the opt-out flag in the same shell session that spawns Claude Code:

export OPT_OUT_INSTRUMENTATION=true

On Windows PowerShell:

$env:OPT_OUT_INSTRUMENTATION = "true"

Set this before launching Claude Code, not after. The MCP server reads the env var at spawn time.

Next Steps

You now have docs lookup and schema validation inside Claude Code. The natural progressions:

• Add live store mutations. The Dev MCP is read-only by design. To let Claude push theme edits, run bulk product updates, or adjust inventory, install the full Shopify AI Toolkit plugin (Method 2 above) and follow the live-store warning section in our Shopify AI Toolkit pillar. Mutations against a connected store happen immediately with no preview, so test on a development store first.
• Cut MCP context costs. The Dev MCP alone is light, but the moment you wire a second or third MCP server (Meta, Klaviyo, GitHub), context inflates fast. MCP Tool Search drops a multi-MCP setup from ~12K context tokens to roughly 600 by loading tool definitions on demand.
• Add more vendor MCPs. Once the Shopify Dev MCP is stable, the 50+ best MCP servers guide curates the production-ready additions (Meta, Klaviyo, GitHub) worth wiring next.

If you're building an actual ecommerce operator workflow on top of this rather than tinkering, the Shopify Kit ships 180+ files of CRO, paid media, retention, SEO, ops, and architecture playbooks designed to pair with the AI Toolkit. The Dev MCP gives Claude Code documentation and validation. The kit gives Claude Code judgment about what to actually do with them.