Shopify Dev MCP for Claude Code: 2026 Setup

Why Shopify Dev MCP Changes How Claude Code Works On Your Store

Ask Claude Code to write a Shopify Admin API mutation without the Dev MCP server connected and you will, roughly half the time, get a confident-looking GraphQL block that references fields Shopify retired two years ago. Ask it to write a Liquid filter, and you might get {% assign price = product.price | money_with_currency %} — a filter that has never existed in Liquid, but looks plausible enough to ship.

This is what "AI hallucination" looks like in Shopify development, and it costs hours of debugging per week. The fix is not a better prompt. The fix is grounding your agent in Shopify's actual documentation and live GraphQL schemas, which is exactly what the shopify dev mcp for claude code combo does. It is first-mover territory — the toolkit only landed in April 2026 — and most Shopify merchants building with Claude Code have not set it up yet.

This guide walks through the five-minute install, the CLAUDE.md configuration that makes it actually work on Shopify projects, example prompts that only succeed because MCP is connected, how Dev MCP differs from Storefront MCP and Customer Account MCP, and the debugging steps to run when the server stops responding. If you want the broader context on pairing Claude Code with your store, start with our pillar on Claude Code for Shopify development and then come back here for the MCP layer.

What Shopify Dev MCP Actually Does

Dev MCP is a local MCP server, maintained by Shopify, that exposes a handful of tools to any MCP-compatible AI client — Claude Code, Cursor, Codex, Gemini CLI, VS Code, and others. When connected, your agent can fetch the live Shopify docs, introspect GraphQL schemas, and validate its own code before offering it to you.

The server ships with six core tools, according to Shopify's Dev MCP documentation:

• `learn_shopify_api` — the orientation tool the agent calls first, which tells it which APIs and surfaces are currently supported.
• `search_docs_chunks` — semantic search across shopify.dev for targeted doc snippets.
• `fetch_full_docs` — pulls a complete documentation page when chunks are not enough.
• `introspect_admin_schema` — live GraphQL schema introspection for Admin, Storefront, Partner, Customer Account, Payments Apps, and Function APIs.
• `validate_graphql_codeblocks` — runs a generated GraphQL snippet against the real schema and reports hallucinated fields.
• `validate_theme_codeblocks` — validates Liquid and Polaris web component usage against current spec.

The practical impact is that Claude Code stops guessing. Instead of pattern-matching on whatever Liquid and GraphQL appeared in its training data — some of which is from 2021 — it queries the source of truth every time. Shopify ships schema changes quietly, and Liquid filters get deprecated; a grounded agent catches these where a pattern-matching one does not. For a deeper look at how this fits into the Shopify AI ecosystem, Weaverse's 2026 analysis of the Shopify AI Toolkit has a good breakdown.

Prerequisites: What You Need Before Install

Setup is genuinely quick, but skipping the prerequisites wastes the time you think you are saving. Before running the install command, confirm the following:

1. Node.js 18 or higher installed and on your PATH. Run node --version to verify. Most Shopify developers already have 20 or 22 from the Shopify CLI.
2. Claude Code installed and authenticated. If you are brand new, Anthropic's Claude Code overview covers the auth flow.
3. A local project directory you are comfortable running Claude Code inside. MCP configured at the project level lives in a .mcp.json file in that directory.
4. Shopify CLI (optional but recommended) for app and theme projects, so shopify theme dev and shopify app generate are available in the same shell session.

You do not need a Shopify Partners login, a store API token, or OAuth credentials to run Dev MCP — it only reads public developer documentation and schemas. That is a meaningful distinction from the other two MCPs we will cover later.

The Five-Minute Install for Claude Code

Here is the single command that connects Claude Code to the Dev MCP server, straight from a terminal inside your project directory:

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

That is it. The command registers the server at project scope, uses npx to always pull the latest @shopify/dev-mcp package, and communicates over stdio — which is the simplest MCP transport and the one with the fewest moving parts.

After running it, verify the server is live:

claude mcp list

You should see shopify-dev-mcp with a status of connected. If you want the install scoped globally across all your projects instead of just the current one, add --scope user. For more on MCP scopes and management, Claude Code's MCP docs cover claude mcp get, claude mcp remove, and how configuration precedence works.

If You Prefer Editing .mcp.json Directly

Some teams like checking the MCP config into git so every contributor gets the same server list. Drop this into .mcp.json at your project root:

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

Claude Code picks this up on the next session start. Keep secrets out of this file — Dev MCP does not need any, but if you later add a server that does, use ${ENV_VAR} expansion and load from a gitignored env file.

CLAUDE.md Configuration for Shopify Projects

Installing the MCP server is step one. Getting Claude Code to actually use it on every Shopify question is step two, and that is what your project's CLAUDE.md file is for.

CLAUDE.md sits at your repo root and is loaded into context at the start of every session. Without explicit instructions, Claude Code will sometimes answer a Shopify question from memory even though Dev MCP is connected. A short, opinionated block at the top of CLAUDE.md solves this. Here is a minimal version that works well on Shopify theme and app projects:

# Shopify MCP Usage Rules

This project uses the Shopify Dev MCP server. You MUST:

- Call `learn_shopify_api` once per session before answering any
  Shopify-specific question.
- Call `validate_graphql_codeblocks` before proposing any GraphQL
  query or mutation. Reject and rewrite any block the validator flags.
- Call `validate_theme_codeblocks` before proposing Liquid or Polaris
  web component code. Do not ship filters, tags, or components the
  validator does not recognize.
- Call `introspect_admin_schema` when the user mentions a mutation
  or query you have not verified this session.
- When in doubt between two approaches, call `search_docs_chunks` and
  cite the doc URL in your answer.

For a fuller pattern, including agents and skills conventions, our walkthrough of the best Claude Code subagents for Shopify merchants shows how to split Shopify work across task-specific agents, each with their own MCP rules.

Keeping the Token Budget Reasonable

Every connected MCP server costs context window tokens because its tool definitions load upfront. Dev MCP alone is lightweight — roughly 2–3k tokens — but if you are stacking five MCP servers, that adds up. Use Claude Code's Tool Search feature to lazy-load tool definitions only when needed, which Builder.io's MCP server guide documents well. On a Shopify-only project, Dev MCP alone is usually fine.

Example Prompts That Only Work Because MCP Is Connected

The best way to see the difference is to run a few prompts that would otherwise hallucinate. Each of these returns valid, working code only when Dev MCP is active.

Prompt 1: Liquid that touches current tag behavior

"Build a section that renders the top three bestsellers using the product GraphQL type, filtered by publishedStatus, and falls back gracefully if the collection is empty. Use validate_graphql_codeblocks and validate_theme_codeblocks before showing me the code."

Without MCP, Claude Code will cheerfully generate a publishedAt filter or an older REST fallback. With MCP, it introspects, finds the correct field, validates, and ships.

Prompt 2: An Admin API mutation with the right scopes

"Write the GraphQL mutation to update a product variant's inventory policy. Tell me which access scope the app needs. Validate the mutation."

The validator catches wrong field names immediately. The scope comes from introspect_admin_schema, which includes scope metadata — something pattern-matching cannot fake.

Prompt 3: A Shopify Function

"Scaffold a Shopify Function for a discount that applies 10% off when the cart contains two or more items tagged bundle. Use fetch_full_docs to confirm current function input/output schemas."

Functions change often. Grounding in fresh docs is the difference between a function that compiles and 30 minutes of "why does cart.lines.node.merchandise not exist."

Prompt 4: Polaris web components

"Build an embedded admin page that lists orders in a Polaris DataTable with pagination. Validate all component usage."

Polaris shipped web components in 2026 and continues to evolve. Shopify's Polaris MCP docs confirm the validator catches stale component props immediately. For more on embedded admin patterns, Shopify app development fundamentals covers the surrounding architecture.

Formula for a Prompt That Uses MCP Well

Think of every prompt as having three parts:

• Intent — what the merchant wants (the feature).
• Constraints — the surface (Admin API vs Storefront vs Liquid) and any scope or plan requirement.
• Verification — which MCP tools the agent must call before showing code.

Writing the verification step explicitly into the prompt forces the tool call and stops the agent from defaulting to memory.

Dev vs Storefront vs Customer Account MCP: Pick the Right One

Shopify ships three MCP servers, and they serve entirely different purposes. Developers regularly pick the wrong one, wire it up, and then spend hours wondering why their AI assistant cannot read order history (Dev MCP does not handle orders) or why it refuses to write code (Storefront MCP is for shoppers, not developers).

Sources: Shopify Dev MCP docs, Storefront MCP docs, and Customer Account MCP docs.

For developer workflows inside Claude Code, Dev MCP is the only one that matters. Storefront and Customer Account MCPs are for merchant-facing agent experiences — think: a conversational shopping assistant on your storefront, not your IDE. If you are building a customer-facing agent on top of your store, pair Storefront MCP for browsing with Customer Account MCP for logged-in flows. If you are writing code, stay on Dev MCP.

When to Add a Second MCP Server

Most Shopify developers only need Dev MCP plus one or two general-purpose servers. Common additions include a GitHub MCP for PR and issue workflows, and a Postgres or database MCP if your app has a backend. Our writeup on Claude Code + Shopify CLI integration covers how to let Claude drive shopify theme push, shopify app deploy, and related CLI commands alongside Dev MCP.

Security & Scope: What Dev MCP Can and Cannot See

Dev MCP is the lowest-risk MCP server in the Shopify ecosystem because it is read-only against public data. No store tokens, no customer data, no ability to write to your store. PolicyLayer's Shopify Dev MCP policy summary lists exactly six tools, all of which are introspection or validation — none mutate anything.

That said, a few practical security notes still apply:

• Run Claude Code from inside the project directory you intend to edit. Scope matters. A broad working directory widens the surface of "allow-listed" file edits Claude Code can perform.
• Review MCP config on pull request. Check .mcp.json into git and review it like any other config change. A rogue MCP server with file-system access is the real risk, not Dev MCP.
• Separate Dev MCP from store-operations MCPs. If you later add a server that authenticates to your store (for example, to manage orders or products), keep it on a staging store, not your live one. Development happens on Dev MCP; write operations happen with explicit tokens.
• Do not paste store tokens into chat. If an agent needs to authenticate, route it through an MCP server's env vars, not through prompt content. Claude Code's settings docs cover how environment variables flow from your shell into MCP subprocesses.

For broader patterns on AI tooling hygiene inside an ecommerce stack, our AI emerging tech library has adjacent guides on private LLMs and data boundaries.

Debugging When the MCP Server Is Not Responding

When Dev MCP silently stops working — usually after a Node upgrade, a Claude Code update, or a registry hiccup — the debugging flow is short. Run these in order:

1. `claude mcp list` — confirm the server is registered and its status is connected. If status is failed, you have a startup error. If it is missing, re-run the install command.
2. `claude mcp get shopify-dev-mcp` — prints the exact command being run. Sanity-check the args and transport.
3. Manually spawn the package — run npx -y @shopify/dev-mcp@latest in a terminal. If this hangs, throws, or errors, the problem is the package itself or your Node environment, not Claude Code.
4. Check Node version — node --version must report 18 or higher. Some package updates have silently broken on Node 16 that was upgraded to 18 mid-session.
5. Clear the npx cache — rm -rf ~/.npm/_npx (or %LOCALAPPDATA%\npm-cache\_npx on Windows) and retry. Dev MCP pins to latest, and a corrupted cached tarball will fail until wiped.
6. Restart the Claude Code session — some MCP connection errors are sticky until the session is restarted. Use /reset or quit and relaunch.
7. Check Shopify status — Dev MCP uses shopify.dev endpoints for doc fetches. Rare, but a shopify.dev outage will make fetch_full_docs and search_docs_chunks fail while introspection still works.

Common failure messages decoded:

• `spawn npx ENOENT` — Node or npx is not on the PATH Claude Code sees. Start Claude Code from a terminal that has the right PATH, or hard-code the absolute path in .mcp.json.
• `MCP server failed to start` — usually a Node version mismatch. Check #4 above.
• `Tool call timed out` — a slow network request against shopify.dev. Usually resolves itself; if persistent, check your corporate proxy.

If all else fails, the Shopify Developer Community thread on Claude Code MCP setup problems is a useful troubleshooting reference with fixes from developers who have already been there.

Common Mistakes to Avoid

Even with the install done right, there are a few patterns that make Dev MCP underperform. Avoid these:

• Not writing MCP rules into CLAUDE.md. Connected but un-invoked is the most common failure mode. Claude Code will sometimes skip the tool call if it "feels" confident, even when it is wrong. Explicit rules fix this.
• Leaving the server on `@latest` across team members and hitting version drift. For shared projects, pin to a specific release (@shopify/dev-mcp@1.x.y) and upgrade intentionally. Shopify's MCP changelog lists recent updates.
• Stacking five MCP servers "just in case." Every server consumes context tokens and slows tool selection. Start with Dev MCP, add a second only when you have a recurring need the first does not cover.
• Confusing Dev MCP with a store-operations server. Dev MCP cannot read your orders, update products, or install apps. If you need those, use an app-based MCP with proper OAuth scopes — ideally on a dev store first.
• Ignoring validator output. When validate_graphql_codeblocks flags a field, the answer is not "try a similar field name" — it is "introspect the schema and use the real one."
• Running Claude Code from a directory broader than your project. The wider the working directory, the more file access the agent has. Keep scopes tight.
• Skipping `learn_shopify_api`. This tool tells the agent which Shopify APIs and surfaces are currently supported by Dev MCP. Skip it, and the agent may ask Dev MCP about an API the server does not cover, then fall back to guessing.

Comparison: Best Practice vs Common Mistake

For a related skills-vs-MCP deep dive — when to reach for a Claude Code skill and when to reach for MCP — Fudge AI's Shopify AI Toolkit guide has a clear decision framework.

Where Dev MCP Fits in a Modern Shopify Dev Workflow

A realistic Shopify + Claude Code workflow in 2026 looks roughly like this:

• Start the session inside the project folder. Dev MCP auto-loads.
• Claude Code calls `learn_shopify_api` once. It now knows which APIs are in scope.
• You prompt a feature. The agent calls search_docs_chunks and introspect_admin_schema as needed, writes a plan, and validates any code against the live schema before proposing it.
• You review and accept. Claude Code runs shopify theme push --development or shopify app deploy through the CLI (if configured).
• You commit and push. Standard git workflow.

This is meaningfully faster than the pre-MCP workflow — not because the agent types faster, but because the number of "that doesn't exist" corrections drops to near zero. If you are scaling a Shopify development practice, this compounds quickly across a team. It is one of the few AI tooling upgrades in the Shopify ecosystem that pays for itself in a single afternoon of work.

For the bigger picture — how AI pairs with Shopify development across themes, apps, and functions — our guide on how Claude Code fits Shopify development is the canonical starting point. From there, building a Shopify app from scratch with Claude and the broader shopify-development blog category will fill out the rest of your mental model.

Wrapping Up: Install Dev MCP, Write the Rules, Ship Faster

The shopify dev mcp for claude code combo is a five-minute setup that pays back every single session. You install with one command, write a short CLAUDE.md block that forces validation, and your AI agent stops hallucinating Liquid filters and Admin API fields. The only reason more Shopify developers have not set it up yet is that the toolkit is brand new and the guides are sparse — which is exactly the first-mover window.

Key takeaways:

• Dev MCP grounds Claude Code in live Shopify docs and GraphQL schemas.
• The install is a single claude mcp add command; verify with claude mcp list.
• CLAUDE.md rules force the agent to validate before proposing code.
• Dev MCP is read-only and public — it does not touch your store's data.
• Storefront MCP and Customer Account MCP are different tools for different audiences; developers want Dev MCP.
• Debugging is short: check version, check status, clear the npx cache, restart.

The fastest way to test this is to install Dev MCP right now, paste one of the example prompts from earlier, and watch the validator fire. If you want more Shopify AI tooling patterns and build walkthroughs, browse the Talk Shop blog or drop into the Talk Shop community where Shopify developers share the prompts, rules files, and MCP configs that actually work.

What Shopify task have you been putting off because you did not trust Claude Code to get it right? That is the first task to try again with Dev MCP connected.

About Talk Shop

The Talk Shop team — insights from our community of Shopify developers, merchants, and experts.