Last Verified: October 2026 — tested with @shopify/dev-mcp 1.16.0 against Shopify’s official setup docs
You ask Claude Code for a Shopify Admin GraphQL query, and it confidently uses a field that doesn’t exist, or one Shopify removed two API versions ago. You only find out when the request fails.
The Shopify Dev MCP server is Shopify’s official fix. It gives Claude Code search over shopify.dev, the current API schemas, and a validator that checks GraphQL, Liquid, and UI extension code before you run it. It runs locally, needs no API key, and never touches your store.
Want current docs for other libraries too? Context7 MCP does that for general frameworks; this one goes deep on Shopify.
How it works
Quick Start
Run this once:
claude mcp add --scope user --transport stdio shopify-dev-mcp -- npx -y @shopify/dev-mcp@latestRestart Claude Code and run /mcp to confirm shopify-dev-mcp is connected. Total time: about 2 minutes. Needs Node.js 18 or newer. No account, no token.
⚡ Copy This Prompt: Let Claude Code Install and Verify It For You
Skip the manual steps below and hand the whole job to the agent instead:
You have shell access and the `claude mcp` CLI on my machine. Connect Shopify's Dev MCP server to Claude Code and report back. Do not tell me it's done unless step 5 actually confirms it.
1. Run `node -v`. If it is below v18, stop and tell me to upgrade Node first.
2. Run `claude mcp list`. If a shopify-dev-mcp entry already exists, show it and stop instead of adding a second one.
3. Run `npx -y @shopify/dev-mcp@latest --help` once so the package is downloaded before Claude Code tries to start it (the first download can take longer than the 30-second startup limit). When it prints "running on stdio", the download is done; stop it if it keeps waiting.
4. Run: `claude mcp add --scope user --transport stdio shopify-dev-mcp -- npx -y @shopify/dev-mcp@latest` (on native Windows outside WSL, use `cmd /c npx` instead of `npx`).
5. Run `claude mcp list` and confirm shopify-dev-mcp shows Connected. Then tell me to restart Claude Code.Step 3 prevents the most common failure: a first start that times out while npm is still downloading.
On this page (9 sections)
What You’ll Need
| Requirement | Why You Need It | Time |
|---|---|---|
| Claude Code installed | The client that calls the Shopify tools | 0 min |
| Node.js 18 or newer | The server runs locally through npx | 0–5 min |
| Nothing else | No Shopify login, API key, or store access; it reads public docs and schemas | 0 min |
Step-by-Step Setup
Prefer to do it by hand instead of delegating to the agent? Here’s the manual version.
Step 1 — Check Node and pre-download the package
~2 min
Check your Node version, then pull the package once outside Claude Code:
node -v
npx -y @shopify/dev-mcp@latest --helpOn our machine the cold first download took 109 seconds. Claude Code only waits 30 seconds for a server to start, so skipping this step is the main reason people see “Failed to connect” on day one. When you see Shopify Dev MCP Server v1.16.0 running on stdio, the download is done; press Ctrl+C. After that, the server started in about 5 seconds.
Step 2 — Add the server
~10 sec
This is the command from Shopify’s docs, with --scope user added so it works in every project instead of only the current folder:
claude mcp add --scope user --transport stdio shopify-dev-mcp -- npx -y @shopify/dev-mcp@latestEverything after -- is the server command. If you only build Shopify apps in one repo and want teammates to get it too, use --scope project instead; it writes to .mcp.json, which is safe to commit here because there’s no secret in it.
Step 3 — Windows only: wrap npx
~10 sec
On native Windows (not WSL), launch it through cmd /c:
claude mcp add --scope user --transport stdio shopify-dev-mcp -- cmd /c npx -y @shopify/dev-mcp@latestTyping this in Git Bash? Git Bash rewrites /c into a path (C:/), so the server never starts. We hit exactly that. Either run the command from PowerShell, or prefix it with MSYS_NO_PATHCONV=1. In our test, plain npx without the wrapper also connected, so try that first.
Step 4 — Turn off telemetry (optional)
~10 sec
Release builds send usage events to Shopify, and those can include tool inputs and results. To opt out on macOS or Linux:
mkdir -p ~/.config/shopify-ai-toolkit
touch ~/.config/shopify-ai-toolkit/opt-outOn Windows, create an empty file at %APPDATA%\shopify-ai-toolkit\opt-out. Setting DO_NOT_TRACK=1 in the environment that launches the server works too.
What It Can Do
We started the server and listed its tools. Version 1.16.0 exposes five:
| Tool | What It Does | Example Ask |
|---|---|---|
learn_shopify_api | Loads the guide for one API surface and starts a session; the other tools need its conversation ID | “I’m building with the Admin API” |
search_docs_chunks | Searches shopify.dev and returns doc passages and code examples | “How do I set inventory at a location?” |
validate | Checks GraphQL operations and UI extension code against the real schema | “Write a query for products with stock, then validate it” |
validate_theme | Checks Liquid files and a whole theme folder | “Validate the product section I just edited” |
feedback | Sends Shopify a score of how the tools performed | Called by the agent, not you |
It covers 21 API surfaces, including the Admin and Storefront GraphQL APIs, Functions, Liquid, Hydrogen, Polaris extensions, POS UI, ShopifyQL, and Customer Account. The default API version in our test was 2026-07; tell Claude your version and it passes it to every call.
The Test That Sold Us: It Catches Made-Up Fields
We sent the validator two Admin API queries. The first asked for totalInventory and variant prices, which are real fields. The second asked for stockLevel, a field that sounds plausible but doesn’t exist. That’s exactly the kind of field a model invents.
✘ INVALID Cannot query field "stockLevel" on type "Product".
Each check took about 0.2 seconds. The valid result also told us which access scope the app needs, which saves a trip to the docs when you set up app permissions.
Plugin or MCP Server?
| Option | What You Get | Use It When |
|---|---|---|
| Shopify AI Toolkit plugin | Shopify’s skills plus the same tools, auto-updated | You use Claude Code and want Shopify’s recommended setup |
| Dev MCP server (this guide) | The five tools above, nothing else | You want to see and control exactly what is loaded, or your client has no plugins |
| Agent skills only | Shopify guidance as skills, no MCP tools | You want the lightest context footprint |
Shopify’s docs list the plugin as the recommended route: claude plugin install shopify-ai-toolkit@claude-plugins-official. Don’t install both; you’d load the same tools twice.
Verify It’s Actually Working
claude mcp list✘ shopify-dev-mcp connection timed out after 30000ms → first download still running; do Step 1, then retry
✘ shopify-dev-mcp cmd C:/ npx … → Git Bash rewrote
/c; re-add from PowerShell or with MSYS_NO_PATHCONV=1
Then ask something that needs the live schema:
Using the Shopify Dev MCP, write an Admin GraphQL query that lists 5 products with their variants' SKU and inventory quantity. Validate it before showing it to me.If Claude reports a validation result with a required scope, it’s working.
Common Mistakes to Avoid
- Letting the first start time out. The cold download took us 109 seconds against a 30-second limit. Pre-download with
npx -y @shopify/dev-mcp@latest --help. - Adding
cmd /cfrom Git Bash. The path conversion breaks it silently. Use PowerShell orMSYS_NO_PATHCONV=1. - Expecting it to read your store. It can’t see products, orders, or customers. It knows Shopify’s APIs, not your data.
- Installing the plugin and the server. Same tools, loaded twice. Pick one.
- Ignoring the context cost. The five tool definitions came to about 26,500 characters (roughly 6,600 tokens) in our test. If you only touch Shopify in one repo, add it with
--scope projectthere instead of everywhere. - Skipping validation on small snippets. Short queries are where invented fields hide. If Claude skips the check, ask for it, or use a Claude Code hook to remind it.
Q&A
Do I need a Shopify Partner account or API key?
No. The server reads Shopify’s public docs and schemas and runs without authentication. You only need credentials later, when your own app calls the real Admin API.
Can it change products or orders in my store?
No. It has no store access at all. Managing store data is a different kind of connector; this one is for writing and checking code.
What is LIQUID_VALIDATION_MODE?
The default, full, adds validate_theme for whole theme folders. Set it to partial to drop that tool and check single Liquid blocks through validate instead. Pass it with --env LIQUID_VALIDATION_MODE=partial in the add command.
Does it work alongside other MCP servers?
Yes. It pairs well with a docs server like Context7 for non-Shopify libraries. Our starter pack of no-key MCP servers lists more that need no account.
Official Resources
- Shopify AI Toolkit docs — plugin, skills, and Dev MCP setup for each client
- @shopify/dev-mcp on npm — configuration options and telemetry opt-out
- Claude Code MCP docs —
claude mcp add, scopes, and timeouts
If this saved you a setup headache, follow @quickpromptco on X for the next MCP guide.