Shopify Ai Toolkit plugin

Shopify's Dev MCP server, @shopify/dev-mcp, is a local server that lets a coding agent search Shopify's docs and API schemas and check GraphQL, Liquid, theme and extension code against them. It reads no store data and needs no login. It now sits inside Shopify's AI Toolkit, which also offers a plugin route. We checked it on 31 October 2026.

Quick facts

A naming note. "Shopify MCP" can mean two different things. This page is about the developer server, which helps you write code. Shopify and third parties also publish servers aimed at storefront and store data. Those are different projects with different risks, and we do not cover them here. For the general picture of how agents call tools, see MCP tools. Shopify's docs say the catalog and cart tools on its older Storefront MCP endpoint (https://{shop}/api/mcp) were removed, and point to the Universal Commerce Protocol instead.

What it does

Shopify development rewards precision. Which API surface applies, what fields a GraphQL type has, how an extension's configuration file should look, which CLI command to run. Models trained months ago get these details wrong, and the platform changes on a quarterly API version schedule.

The Dev MCP server's job is to give the agent current facts. Shopify's docs list three things the toolkit connects an agent to:

• Developer docs and API schemas. Look up the right API surface and work from current reference material instead of model memory or broad web search.
• Code validation. Check GraphQL queries, Liquid templates and Shopify Extensions against Shopify's schemas to catch mistakes early.
• Store management. Prepare and run supported store-management tasks through Shopify CLI's authenticated store context, with you choosing when to run them.

The first two are what the MCP server does. Store management goes through the Shopify CLI, using your own login, not through the MCP server's tools.

The tools

The npm README names a few tools and settings, and the docs describe the rest by purpose, so we do not give a full list:

The server also resolves supported package and API version information. Its npm dependencies include the Shopify CLI (3.93.1 or later), theme-check, Hydrogen, Polaris types and App Bridge packages, which tells you which surfaces it knows: apps, themes, Hydrogen storefronts and extensions.

Three ways to install the toolkit

Shopify offers three routes and recommends the first.

Old per-surface skills such as shopify-admin and shopify-liquid are deprecated and receive no updates. If you installed them, Shopify's docs give a remove command and tell you to replace them with the single shopify skill.

Plugin commands

From Shopify's docs:

claude plugin install shopify-ai-toolkit@claude-plugins-official
codex plugin add shopify@openai-curated
agy plugin install https://github.com/Shopify/shopify-ai-toolkit

In Cursor Chat the command is /add-plugin shopify. For skills: npx skills add Shopify/shopify-ai-toolkit.

Install the Dev MCP server in each agent

All five of ours are documented by Shopify for the MCP route.

Claude Code

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

Restart Claude Code to load it.

Codex

In ~/.codex/config.toml. Codex uses TOML with mcp_servers, not JSON with mcpServers:

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

Cursor

In Cursor Settings, Tools and MCP, or .cursor/mcp.json:

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

On Windows, if you see connection errors, Shopify gives this alternative:

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

Antigravity

Shopify documents Antigravity CLI. Add this to ~/.gemini/config/mcp_config.json, then restart:

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

Gemini CLI is now for Code Assist enterprise customers only, so we leave it out.

OpenCode

Shopify does not document OpenCode for this server. Our adaptation, in opencode.json:

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

VS Code

Open the Command Palette, run "MCP: Open User Configuration", and add this to your user mcp.json:

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

A worked use: migrating an extension

Shopify's own example shows where the toolkit earns its keep. Checkout and customer account extensions on API versions before 2025-10 need to adopt Polaris web components when moving to newer versions. The work is repetitive and detail-heavy:

• Update the API version in shopify.extension.toml.
• Convert React-based extension code to Preact where required.
• Replace legacy components with Polaris web components.
• Update extension APIs and target-specific imports.
• Check the migration guide for every required step.
• Run and test the migrated extension locally.

With the toolkit installed, you ask the agent to migrate a named extension to a named API version. The agent searches the current docs, edits the files, and runs validation against the schema. Our reading: validation is the part that makes this safer than a plain model edit, because a wrong field name fails a check instead of reaching a merchant's checkout.

Other jobs that fit the same pattern, from our reading of the tool descriptions:

1. Writing a GraphQL Admin API query and validating it before you run it against a store.
2. Checking a Liquid theme for errors with validate_theme before you push it.
3. Looking up the right Function or extension target for a feature, instead of guessing.

Plugin or MCP server: how to choose

The three routes overlap, and loading more than one is a common mistake. Here is how we would pick, from the documented differences.

The skill's design is worth a note. It covers every developer surface, including the GraphQL Admin API, Shopify Functions, Polaris, Liquid, Hydrogen and the CLI, but the agent reads the guidance for a surface only when a task needs it. That keeps the context small. The same idea applies to your own prompts: name the surface and the API version, so the agent loads the right part.

What a good prompt looks like

The server helps most when you give it a precise target. Compare two requests.

A weak one: "Make my checkout extension work with the new version." The agent has to guess the version, the extension and the goal.

A stronger one: "Migrate extensions/my-checkout-extension to API version 2026-04. Search the docs for the migration guide first, list the steps, then edit the files, then validate the result and show me any errors." That names the file, the version and the order of work, and it asks for the validation step that the server exists to provide.

Two habits make the output safer. Ask for the search step before the edit, so the plan comes from current docs and not memory. And ask for the validation output to be shown to you in full, so a failed check is not summarised away. If a check fails and the agent says it is "probably fine", ask it to fix the error or explain why the check is wrong.

Telemetry

This is the part to read before you roll it out to a team. The npm README says published release builds send usage events to https://shopify.dev/mcp/usage. Events can include tool inputs and results, API and package version metadata, a random conversation ID, and client or model identifiers supplied by the MCP host. Builds run from source send nothing.

Because tool inputs and results can be included, a validation request that contains a snippet of your code may leave your machine. Do not treat the server as fully local just because it runs on your computer.

To opt out across Shopify AI Toolkit surfaces, create an empty user-level file (recommended):

mkdir -p ~/.config/shopify-ai-toolkit
touch ~/.config/shopify-ai-toolkit/opt-out

On Windows the file is %APPDATA%\shopify-ai-toolkit\opt-out. You can also set OPT_OUT_INSTRUMENTATION=true or DO_NOT_TRACK=1 in the environment that launches the server.

Security notes

1. No store credentials in the MCP server. It runs without authentication and reads no store data, so a leak of the server's config exposes nothing about your shop.
2. Store management uses your CLI login. If the toolkit runs store tasks through Shopify CLI, they act with whatever store access your CLI session has. Use a development store, and confirm each action. The docs say you choose when to execute them.
3. Telemetry can carry your code. Opt out if your code or customer data must not leave the machine.
4. Pin or review `@latest`. The recommended entry uses @latest, so each launch can pull a new version of a package with 20 dependencies. Pin a version if you need repeatable builds.
5. Docs content is untrusted. Search results are text. Treat them as reference, not orders.
6. Check theme changes before you push. Validation catches schema errors, not logic or design mistakes.

Limits and known issues

• Developer tool only. It does not answer "how many orders came in today".
• Several overlapping surfaces. Plugin, skills and MCP server overlap. Pick one route so you do not load the same guidance twice.
• Deprecated skills. Older per-surface skills are no longer updated.
• Windows quirk. Cursor on Windows may need the cmd /k form.
• Large install. The npm package unpacks to about 20 MB.
• Open issues. We did not review the repo's issue tracker for this page.

Alternatives

See our skills guide for how agent skills compare with MCP servers.

Our take

We did not run this server for this page. This comes from Shopify's docs and the npm package.

The honest summary is that it is a documentation and validation server for people who build on Shopify. That is a good job for MCP. Platform APIs change often, models know them poorly, and a schema check is a cheap, strong safeguard.

Choose the plugin if your agent supports it, since Shopify recommends it and it updates itself. Use the MCP server directly if you want to see exactly what is running, or if your agent has no plugin system. Set the telemetry opt-out before you share the setup with a team. And if you came here hoping to ask an agent about live orders, this is not the tool.

A short setup checklist

1. Check Node is 18 or higher.
2. Install the plugin for your agent, or add the Dev MCP entry.
3. Create the telemetry opt-out file if your policy needs it.
4. Use a development store for anything the CLI runs on a store.
5. Ask the agent to validate a GraphQL query you already know works, as a first check.
6. Remove any old per-surface Shopify skills.

Frequently asked questions

What is the Shopify Dev MCP server?

It is Shopify's local MCP server, @shopify/dev-mcp, that lets an agent search Shopify docs and API schemas and validate GraphQL, Liquid, theme and extension code. It does not read or change a store's data.

Do I need to log in?

No. The Dev MCP server runs locally over stdio without authentication.

What is the Shopify AI Toolkit?

A bundle of docs and schema access, code validation and CLI store management, installed as a plugin, as agent skills, or through the Dev MCP server.

Does it send telemetry?

Published release builds send usage events, which can include tool inputs and results, to shopify.dev. You can opt out with a user-level file or the DO_NOT_TRACK variable.

Which Node version?

Node.js 18 or higher.