Shopify MCP: Complete Guide (2026)

TL;DR + what you actually need

The Shopify MCP server is a stdio process — a local subprocess your MCP client launches — that bridges Claude or Cursor to Shopify’s GraphQL Admin API, so an agent can read and write real store data in plain language. Four things to know before you start:

• One package: shopify-mcp — not shopify-mcp-server, a different package with the same-sounding name. Run it via npx.
• Credentials, one of two shapes: a Dev Dashboard Client ID + Client Secret (apps created since January 2026) or a static shpat_ access token (older custom apps). Both need your .myshopify.com domain.
• Admin API scopes: pick only what you need — read_products/write_products, read_customers/write_customers, read_orders/write_orders — on the custom app itself.
• No dry-run mode: every mutating tool call is live the moment it runs. Keep destructive tools behind your client’s approval prompt.

The copy-paste, if that’s all you came for:

claude mcp add shopify -- npx shopify-mcp \
  --clientId YOUR_CLIENT_ID \
  --clientSecret YOUR_CLIENT_SECRET \
  --domain your-store.myshopify.com

Also worth knowing before you scroll: Shopify ships a separate, official shopify-dev MCP server that does not touch your store at all — it answers questions about Shopify’s own APIs and docs. The official-vs-community section below draws the line clearly.

What Shopify MCP actually does

You ask “which SKUs are below 5 units at any location?” and the agent queries inventory levels and hands back a restock list. You ask “tag every customer with 3+ orders as VIP” and it reads customers, filters, and writes the tags. Every step is a real GraphQL call against your Admin API, not a guess about what your store contains.

The implementation this guide centers on lives at github.com/geli2001/shopify-mcp — TypeScript, MIT-licensed, maintained by Donny Li. It does no AI work itself: agent calls come in, Shopify GraphQL Admin API calls go out, and your credentials are the only state it holds. That thin-wrapper shape is exactly what you want — the reasoning is your model’s, the source of truth is Shopify.

The maintainer has kept it current with Shopify’s own platform changes, including the January 2026 shift to OAuth client credentials covered next:

That tweet is the maintainer confirming a community PR had just landed client-credentials auth and expanded product-management coverage — the exact update this guide’s auth section is built around.

Auth: two paths, and Shopify changed the default in 2026

As of January 1, 2026, new Shopify custom apps are created in the Dev Dashboard and authenticate with OAuth client credentials instead of a static access token. If your app predates that, the old flow still works. Two real paths, both supported:

• Option 1 — Client credentials (recommended, Dev Dashboard apps). From your Shopify admin: Settings → Apps and sales channels → Develop apps → Build app in dev dashboard. Configure Admin API scopes, install the app, and copy the Client ID and Client Secret. The server exchanges these for an access token and refreshes it automatically — tokens are valid for roughly 24 hours.
• Option 2 — Static access token (legacy custom apps). If you already have a custom app with a static shpat_ token, pass it directly. No migration required, but Shopify is not issuing new static tokens for apps created in the Dev Dashboard.

This is not a hypothetical migration story. On r/shopify, a developer hit a wall trying to connect Claude Desktop to their store: repeated 401 errors on the access token, unable to find it under the path they expected. Their own follow-up comment names the fix — switching to “the new OAuth client credentials flow (Dev Dashboard apps, not the old custom app shpat_ tokens).” A second commenter on the same thread described Claude Code hitting the identical wall, web-searching its way to “it’s because Shopify’s update,” then writing a launcher script to auto-refresh the client-credentials token.

The install card below is wired to the static access-token shape (simplest if you already have a legacy custom app). For a Dev Dashboard app, swap in client-credentials env vars instead:

SHOPIFY_CLIENT_ID=your_client_id
SHOPIFY_CLIENT_SECRET=your_client_secret
MYSHOPIFY_DOMAIN=your-store.myshopify.com

Either way, the credential goes in your MCP client’s env block, never a file you commit.

Official shopify-dev vs community shopify-mcp

Unlike a typical “official vs community” choice, these two servers are not interchangeable — they solve different problems, and mixing them up is the single easiest way to install the wrong one.

A note we verified while researching this guide: the original github.com/Shopify/dev-mcp repository now 404s. Shopify’s own docs currently point to github.com/Shopify/Shopify-AI-Toolkit as the source, part of a broader open-source AI Toolkit Shopify published in April 2026. The npm package name (@shopify/dev-mcp) and install command are unchanged, so existing installs keep working; only the GitHub link moved. See /servers/shopify-dev for our catalog entry.

Two more official, store-hosted servers worth knowing about, both out of scope for this admin-focused guide: Shopify Storefront MCP for customer-facing shopping agents, and Shopify Customer Accounts MCP for authenticated customer self-service. Both are official, remote, hosted per store — not something you self-host like the two servers above.

Install (every client)

shopify-mcp is stdio-only — your MCP client launches npx shopify-mcp as a subprocess with your credentials as arguments or env vars. Requires Node.js 18+ and a Shopify custom app. The install panel below pulls its config from the canonical /servers/shopify catalog entry, so it stays in sync with the package name and argument shape.

One-line install · Shopify

Open server page

Install

Cursor

One-click install

VS Code

One-click install

Claude Desktop

Copy configuration

Claude Code

Copy CLI command

CLI

Gemini

Copy CLI command

CLI

Codex

Copy CLI command

CLI

Windsurf

Copy configuration

ChatGPT

Add via Settings → Connectors

M

Manual

Copy configuration

Client-specific notes:

• Claude Code — one line, either auth style:

  claude mcp add shopify -- npx shopify-mcp \
    --accessToken YOUR_ACCESS_TOKEN \
    --domain your-store.myshopify.com

  Full flag reference at /clients/claude-code.
• Claude Desktop — paste the JSON block from the install card into claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%/Claude/), then restart the app. See /clients/claude-desktop.
• Cursor — same JSON shape in ~/.cursor/mcp.json. See /clients/cursor.
• VS Code / Windsurf — the JSON snippet from the install card goes in the client’s MCP config file (~/.codeium/windsurf/mcp_config.json for Windsurf).

Prefer environment variables over CLI flags? Create a .env file next to where you run the server (or set the same keys in your client’s env block):

SHOPIFY_ACCESS_TOKEN=your_access_token
MYSHOPIFY_DOMAIN=your-store.myshopify.com

then run npx shopify-mcp with no flags at all. Add --apiVersion (or SHOPIFY_API_VERSION) if you need to pin a specific Shopify API version; it defaults to the current stable release.

Codex CLI

Codex reads MCP servers from ~/.codex/config.toml:

[mcp_servers.shopify]
command = "npx"
args = ["shopify-mcp"]

[mcp_servers.shopify.env]
SHOPIFY_ACCESS_TOKEN = "your_access_token"
MYSHOPIFY_DOMAIN = "your-store.myshopify.com"

Restart Codex and confirm with codex mcp list. Browse every supported client and its config path at mcp.directory/clients.

Tools: the Admin API surface

As of this writing, the README lists 31 tools across six resource groups, all built on Shopify’s GraphQL Admin API (currently pinned to the 2026-01 schema by default). List tools share cursor-based pagination (after/before), a sortKey, and pass-through Shopify query syntax for filtering — so query: "status:active vendor:Nike tag:sale" works exactly like it does in the Shopify admin search bar.

Products (8 tools) — full CRUD, variants, options

get-products and get-product-by-id cover search and lookup; create-product, update-product, and delete-product handle the lifecycle; manage-product-options plus a variant-management tool round out the group. One sharp edge documented directly in the README: create a product with inline productOptions and Shopify registers every option value but generates only one default variant — first value of each option, priced at $0. You need a follow-up variant-management call with a REMOVE_STANDALONE_VARIANT strategy to generate the real, priced variants.

Customers (8 tools) — CRUD, merge, addresses

Full create/read/update/delete on customer records, plus a merge tool for consolidating duplicates and address management. Useful pairing: filter by order count, then bulk-tag the result — that’s recipe 4 below.

Orders (10 tools) — the biggest group

Smart lookup, cancel, close/open, mark-as-paid, fulfillment creation, and refunds. This is where the blast radius is highest — a cancel or refund call is irreversible the moment it runs, which is exactly why the safety section below exists.

Metafields (3), inventory (1), tags (1)

get-metafields, set-metafields, and delete-metafields work on any resource — products, orders, customers — which makes them the tool of choice for theme-specific merchandising fields the standard admin UI does not expose well. inventory-set-quantities sets absolute stock levels at a location (not deltas — read the current value first if you only want to adjust it). A single tag-management tool adds or removes tags on any taggable resource.

Scopes & token safety

The Admin API scopes you grant — not the MCP server itself — are the real permission boundary. When you configure the custom app, you choose exactly which of read_products/write_products, read_customers/write_customers, read_orders/write_orders (and any others) it receives. An agent holding that credential can do anything those scopes allow and nothing else — so a reporting-only integration should get read scopes and stop there.

Two things to weigh before you hand an agent write scopes. First, this server ships no dry-run mode — every create-product, delete-product, order-cancel, or refund call is live the moment the tool runs. Second, an open pull request auditing the tool surface for AI-agent usability flagged that some order tools’ customer-notification parameters could send a real email or SMS to a customer without an explicit confirmation step. Neither is resolved as of this writing — treat both as reasons to keep destructive and customer-facing tools behind your client’s approval prompt, not auto-approved.

A community voice worth taking seriously: on r/shopifyDev, one developer put the risk plainly, warning that turning this into a production integration “will quickly run into Shopify’s API rate limits and the terrifying risk of AI hallucinations modifying live store data (like messing up inventory or prices)” and that “letting an LLM loose on a production store’s write-endpoints requires serious guardrails.” A separate open pull request proposes wrapping the server with an armorer-guard mcp-proxy layer — a local check for prompt injection and dangerous tool calls before a request reaches Shopify — but it is not merged, so it is not something you get by default today.

Our take: test destructive recipes against a Shopify development store, or against a narrow product/tag filter, before pointing an agent at your full live catalog.

Recipes

Six workflows where the install pays for itself. All assume the server is registered and credentials are valid.

Recipe 1 — Bulk price sweep for a sale

“Put every product tagged ‘summer’ on 20% off, and set compareAtPrice to the original price so the sale shows a strikethrough.” The agent calls get-products with query: "tag:summer", then updates price and compareAtPrice across the result set. Check a couple of products on the live storefront afterward — that field is what makes the strikethrough render.

Recipe 2 — Inventory audit across locations

“Which SKUs are below 5 units at any location, grouped by product?” Read-only, so it is safe to run any time — a good first test right after install. The agent reads inventory levels per location and hands back a restock list instead of you scrolling the admin.

Recipe 3 — Order triage and fulfillment queue

“Show unfulfilled orders older than 2 days, oldest first, and draft the fulfillment for each.” get-orders with a status filter, then a fulfillment call per order ID. Keep fulfillment creation behind an approval prompt the first few times — a wrong order ID ships the wrong package.

Recipe 4 — Customer segment tagging

“Tag every customer with 3 or more orders as VIP, and list their emails for the loyalty campaign.” get-customers filtered by order count, then a bulk tag call. Cheaper than exporting a CSV to a spreadsheet tool just to filter it.

Recipe 5 — Draft-product generation from a spec

“Create 12 products from this list: title, price, and Small/Medium/Large sizes for each.” create-product plus manage-product-options. Remember the one-default-variant gotcha from the tools section before you assume pricing landed on every size.

Recipe 6 — Metafield-driven merchandising

“Add a ‘care instructions’ metafield to every product in the Apparel collection, pulled from this reference doc.” set-metafields keyed by product handle. Useful for fields your theme reads but the standard admin UI does not expose well.

Gotchas we hit (and what Reddit + the issue tracker taught us)

A store-management connector is unusually easy to trust and unusually expensive to get wrong, because a write call can succeed against the wrong assumption just as easily as the right one. Here is what actually bites people, each traced to a real source.

• We assumed the static access token was still the default. It is not. Since January 1, 2026, new Shopify custom apps use Dev Dashboard client credentials, not shpat_ tokens. Two independent r/shopify users hit this exact wall — both resolved it by switching to client credentials once they realized it was a platform change, not a config mistake.
• The product-options gotcha bites real users, not just docs readers. Create a product with inline options and Shopify generates one $0 default variant, not the full matrix. Skip the variant-management follow-up call and your new product looks published with every price reading zero.
• Do not install the similarly named package. The README calls this out directly: the command is shopify-mcp, not shopify-mcp-server — a different package that throws a stale SHOPIFY_ACCESS_TOKEN environment variable is required error even when you pass credentials correctly. One closed GitHub issue is exactly this mix-up.
• Published npm can lag the GitHub repo. An open issue (as of this writing) flags that a batch of merged features had not been published to npm yet, so npx shopify-mcp was serving an older build than the README described. If a documented tool does not show up, check the published version before you assume your config is broken.

Limits & cost

• Admin API rate limits apply. Shopify’s GraphQL Admin API meters by query cost, not just request count. A loop that calls get-orders or get-products one page at a time across a large catalog can burn through that budget fast — tell the agent to batch and use cursor pagination instead of iterating per item.
• Large responses flood context. An open pull request auditing the tool surface notes that GET tools return every field by default, which can dump far more than an agent needs into its context window. Scope requests with searchTitle, a query filter, or a tighter limit instead of asking for everything.
• One store per server instance. No built-in multi-store routing yet — a community feature request for it is still open. Register a separate instance, with its own name and credentials, per store.
• Comprehensive error handling, per the README — auth and API errors return clear messages rather than opaque failures, which matters when a scope is missing or a token just expired.

Cost of the server itself: zero. MIT-licensed, and the Admin API is available on Shopify’s standard plans. You are spending your own API rate-limit headroom and your AI client’s usage, nothing else — a solid entry on our Developer Tools category for that reason.

Troubleshooting

The verdict

The 26-comment r/shopify thread on this exact topic is itself a signal: merchants clearly want their store connected to an agent, and the friction people hit is almost always Shopify’s own 2026 auth changes catching up with them — not a flaw in the MCP server.

FAQ

Sources

• Primary — community implementation, README, issues, and PRs: github.com/geli2001/shopify-mcp (MIT, TypeScript, shopify-mcp on npm)
• Primary — official Shopify Dev MCP docs: shopify.dev/docs/apps/build/devmcp and github.com/Shopify/Shopify-AI-Toolkit (@shopify/dev-mcp on npm)
• Community — maintainer on the January 2026 auth update: @DonnyLi2001, February 23, 2026
• Community — r/shopify auth-migration thread: “Connecting Claude AI to Shopify via MCP” · r/shopifyDev on production risk: “Did anyone connect Shopify’s MCP with Claude” · r/ClaudeCode on disconnects: “Issues with Shopify MCP”
• Community — open pull requests referenced above: AI-agent usability audit #14, Armorer Guard proxy #20
• Canonical MCP.Directory entries: /servers/shopify · /servers/shopify-dev · /servers/shopify-storefront · /servers/shopify-customer-accounts
• Related guides: n8n MCP · Awesome MCP Servers (2026)