Shopify MCP and AI Toolkit: Run Your Store from Claude Code
Install the Shopify MCP server and AI Toolkit in Claude Code. Validate GraphQL, edit themes, run bulk product ops, control live stores.
Agentic Orchestration Kit for Claude Code.
Problem: Running a Shopify store at scale means stitching together a patchwork of admin tabs, third party apps, GraphQL playgrounds, and stale documentation. By the time you find the right metafield definition or write a clean bulk update mutation, the campaign you were building it for is already over.
Quick Win: The official shopify mcp server, packaged inside the Shopify AI Toolkit, turns Claude Code into a hands-on store operator. One command installs the plugin, and you go from "where is that setting?" to "Claude updated 1,200 product tags in 90 seconds."
This guide covers the entire Shopify MCP surface: the three components Shopify shipped, how to install each one (including the standalone shopify dev mcp install flow), what they actually do on a live store, the mutation behavior you must understand before you grant scopes, and how the toolkit slots into a real ecommerce workflow alongside Meta Ads and creative production.
What Shopify Just Shipped: The Shopify MCP Server Stack
On April 9, 2026, Shopify open-sourced the Shopify AI Toolkit at github.com/Shopify/Shopify-AI-Toolkit under MIT license. It packages the company's official Shopify MCP server stack, agent skills, and a Claude Code plugin into a single namespace. Three weeks later, the Winter 2026 Edition extended it with Storefront MCP shipping inside Hydrogen 2026.1.4, turning every Hydrogen storefront on Oxygen into an AI agent endpoint by default.
Before April 9, the only way to run Shopify operations from Claude Code was through community-maintained Shopify MCP servers (the most prominent being GeLi2001/shopify-mcp), which broke whenever Shopify shifted their Admin API. Now there is a vendor-owned path with the same release cadence as the platform itself. The plugin path auto-updates. The schema bundled with the Dev MCP server tracks the live API. And the Storefront MCP endpoint at https://{shop}.myshopify.com/api/mcp is just there, no install step required, on every store running on the Winter 2026 release.
The naming is the source of most confusion. People search shopify mcp and shopify mcp server, but the marketing umbrella is Shopify AI Toolkit, and inside it sit three distinct surfaces. Knowing which one you need before you start typing install commands saves an afternoon of wrong turns.
The Three Shopify MCP Components: Plugin, Dev MCP, Storefront MCP
The toolkit is not one thing. It is three separately-deployable Shopify MCP surfaces under a single brand, each solving a different operator problem.
1. The Shopify Plugin is the recommended entry point for Claude Code users. It bundles every official agent skill (a shopify admin api client for Admin GraphQL, theme development, headless commerce, custom data, Functions, UI extensions) and adds the Dev MCP server underneath. Updates ship automatically, so you never run a stale schema. If you do not have a strong opinion about the others, install this one.
2. The Dev MCP server is the local stdio Shopify MCP server that Claude Code talks to for documentation lookup and validation. It runs on your machine, requires no auth, and exposes tools for searching Shopify's docs, validating GraphQL Admin and Storefront queries against the live schema, and validating Liquid templates against the theme schema. You can install it standalone if you want the validation surface without the plugin's full skill set.
3. The Storefront MCP is Shopify's hosted, public-by-design endpoint that AI shopping agents call to browse products and build carts on behalf of customers. It is not a tool you install. It is a URL: https://{shop}.myshopify.com/api/mcp for cart and policies, plus https://{shop}.myshopify.com/api/ucp/mcp for catalog tools through the Universal Commerce Protocol. Every Hydrogen 2026.1.4 storefront proxies it automatically when proxyStandardRoutes is enabled (the default).
A fourth surface deserves a mention even though it is not part of the formal toolkit: MCP UI (shopify mcp-ui), Shopify Engineering's interactive-component layer that lets MCP servers return rendered cards, forms, and product blocks instead of plain text. The Storefront MCP catalog tools already emit MCP UI payloads, and the Shopify Engineering blog post titled "Breaking the text wall with interactive components" is the canonical primer. Worth knowing the term exists.
The biggest mental shift: Dev MCP is what Claude uses to help you build, Storefront MCP is what other AI agents use to shop your store. Most operators only need the first, which is what the plugin gives you. For protocol context, see our MCP basics guide.
Installing the Shopify AI Toolkit Plugin in Claude Code
The recommended path takes two commands and roughly thirty seconds.
Prerequisites: Node.js 18 or higher (node --version to verify), Claude Code installed, and a working terminal. You do not need a Shopify store to use the documentation and validation surfaces. You only need credentials when you want Claude to mutate live data.
Step 1: Add the marketplace
This registers Shopify's plugin namespace inside Claude Code's plugin marketplace registry. It does not download anything yet.
Step 2: Install the plugin
This pulls in every agent skill plus the Dev MCP server. Restart Claude Code if your terminal does not pick the plugin up immediately.
To verify, ask Claude something like "what's the current GraphQL Admin mutation for creating a product variant?" If the plugin is wired correctly, Claude calls the Shopify docs tool and replies with a current mutation, not a guess from training data.
The plugin also installs cleanly on Cursor (via the Cursor Marketplace), Gemini CLI (gemini extensions install https://github.com/Shopify/shopify-ai-toolkit), VS Code (Command Palette Chat: Install Plugin From Source), and OpenAI Codex (/plugins command). If you arrived from a Cursor tutorial, our Cursor MCP setup walkthrough translates the patterns one-to-one.
If you ever need to bypass the plugin and grab a single skill directly, npx skills add Shopify/shopify-ai-toolkit --skill shopify-admin installs only the GraphQL Admin skill. The trade-off is that manual skill installs do not auto-update, so the bundled schemas drift from the live platform until you reinstall.
Shopify Dev MCP Install: Setting Up the Server Directly
Some operators prefer to run the shopify dev mcp server standalone, separate from the plugin. Reasons to run a manual shopify dev mcp install: you want the validation surface without the full skill bundle, you are wiring Claude Code to a CI environment where plugin auto-updates are a problem, or you are testing against a specific server version pinned in lockstep with another integration.
Claude Code:
That is the verbatim command from shopify.dev/docs/apps/build/devmcp. Stdio transport means Claude spawns the MCP server as a local subprocess. No port. No public surface. The --transport stdio flag is required because that is how the package ships.
Cursor / Gemini CLI users add it to mcp.json:
VS Code uses a slightly different schema in its user-level config:
Codex CLI uses TOML at ~/.codex/config.toml:
Once installed, the server exposes documentation search, GraphQL Admin and Storefront query validation, Liquid template validation, and UI extension validation. None of these touch a real store. They run against the schema and your local code, which is exactly the right starting point. For a refresher on how to think about MCP server configuration in general, the configuration basics guide lays out the patterns we use across every install in our docs.
One last detail: validation payloads are transmitted to Shopify servers by default for instrumentation. If you handle proprietary schemas or client work under NDA, set the opt-out flag before your first validation:
Run that in the same shell session that spawns Claude Code, and the Dev MCP server stops sending telemetry.
The Live Store Warning: Mutations Are Immediate
This section exists because the Shopify AI Toolkit will, on command, change real data on a real store with real customers, and it will do so without a confirmation step that you can audit later. Read this before you ever grant write scopes.
When Claude executes shopify store execute --allow-mutations against a connected store, the change happens immediately. No draft. No preview. No scheduled rollout. No built-in audit trail at the toolkit layer. No rollback button. If Claude generates a mutation that drops every product price by 99% because of a misread instruction, those prices are live the moment the call returns. The only way to fix it is another mutation.
This is not an opinion. The official Shopify documentation, the Shopify Engineering team's release notes, and the community Q&A all confirm the same behavior: test on a development store or a duplicate theme first, then point Claude at production. Production is not where you discover what scope write_products actually grants.
A few specific protections every operator should put in place before they connect:
Authenticate with minimum scopes. When you run shopify store auth --store yourstore.myshopify.com --scopes write_products,read_products, only request the resources you intend to touch in this session. Shopify scopes grant access to entire resource categories, not individual items. write_products lets Claude change every product, not the three you had in mind.
Run the first ten sessions on a dev store. Spin up a free development store, clone your theme, and let Claude execute every workflow against dev until you have a feel for how it interprets ambiguous instructions. The cost of a wrong mutation on a dev store is zero.
Treat permission management as a real surface. Our permission management guide explains the Claude Code patterns we use to gate destructive operations. The TL;DR: configure bash and CLI tool calls to require explicit allow per command, not session-wide approval. Slow down the loop where it matters.
Push themes unpublished first. When Claude edits Liquid, run shopify theme push --unpublished and inspect the preview before swapping the live theme. The toolkit does not enforce this. You enforce it through your prompt and your shell.
Process bulk operations one resource at a time on critical paths. A bulk metafield update that touches 5,000 SKUs should be a hundred 50-SKU batches, not one 5,000-SKU call, when the operation is irreversible.
This is exactly the gap the Shopify Kit was built to close. The kit ships 24 production operations files (catalog, inventory, fulfillment, customer service, returns, finance, fraud) with paired Python automation scripts, plus a _brand-template/ that pre-configures permission patterns and rollback protocols for each surface the toolkit can touch. The Shopify MCP gives Claude Code hands; the Shopify Kit adds the audit layer, the rollback patterns, and the senior-operator playbooks the toolkit deliberately leaves to you.
Eight Workflows You Can Run Today
Once the plugin is installed and you have authenticated against a dev store, here are the operator workflows that pay back the install cost in the first session. Each is something we have run, not something we found in a press release.
1. Bulk product CRUD. "Create a collection for everything tagged summer-2026, set dynamic pricing at 15% off MSRP for variants over $50, and write SEO-optimized descriptions for the products that are missing them." Claude validates the GraphQL mutation against the live schema, executes it through the CLI, and reports the count of objects modified. Standard plans cap GraphQL at 1,000 cost points per minute, so very large catalogs need batching.
2. Theme edits with Liquid validation. Ask Claude to add a "frequently bought together" block to product pages. The Dev MCP server validates the Liquid template against your active theme schema before the file is written, catching missing variables and undefined filters before they hit production. Combine with shopify theme push --unpublished and you get a zero-downtime preview workflow.
3. Metafield definitions and structured data. Define a product.specifications JSON metafield, populate it across 800 SKUs from a CSV, and surface it on the storefront via theme block. This was a four-day consultant engagement before the Dev MCP server made the schema introspectable from inside Claude Code.
4. GraphQL Admin query validation before execution. Paste any GraphQL mutation and ask Claude to validate it. The Dev MCP returns the exact field-level errors the live API would return, so you fix syntax in chat before any HTTP call leaves your machine. This is the workflow that pays the install cost back fastest for developers.
5. Inventory adjustments across locations. "Move 200 units of SKU X-100 from warehouse A to warehouse B, and adjust the available counts on locations C and D so total reflects committed-but-not-fulfilled." Claude resolves the location IDs, builds the inventory adjustment mutation, and executes. What used to be a half-day spreadsheet exercise becomes a single prompt with the right scopes attached.
6. Customer query and segmentation. "Pull every customer who bought in the last 60 days, has a lifetime value over $300, and never opened a Klaviyo email." Claude builds the query, runs it against the Customer API, and emits a CSV. From there you pipe it into your retention stack.
7. Order queries and refund automation. "Refund every order matching SKU Y-200 shipped between 2026-04-15 and 2026-04-20 because of a fulfillment defect." Claude validates the refund mutation, checks for partial-fulfillment edge cases, and executes. Always run this kind of query against the Orders API in read-only mode first to confirm the result set before granting write_orders.
8. Functions configuration. Define a Shopify Function for tiered shipping discounts, validate the GraphQL configuration mutation, and deploy. The plugin's shopify-functions skill walks Claude through the Function template structure, so you get a working Function deployment without rebuilding the boilerplate from memory.
If you want a structured engagement framework around these workflows rather than running them ad-hoc, the Shopify Kit's 90-Day Audit Sequence playbook walks a store through bulk operations, metafield architecture, theme audits, inventory hygiene, and Functions configuration in the exact sequence the AI Toolkit's surface area unlocks. It is the named playbook the kit's architecture/ skills sequence end-to-end, designed to make AI Toolkit access pay back as agency-replacement work.
Storefront MCP and Hydrogen 2026.1.4
The Storefront MCP is a different audience from everything above. It is not for you, the developer or operator, sitting in Claude Code. It is for ChatGPT, Perplexity, Claude.ai, and every other AI shopping agent that wants to browse your catalog and complete a checkout on behalf of a real customer. It is the agentic-commerce surface.
If you run a Hydrogen storefront, this is largely automatic in 2026.1.4 and later. The proxyStandardRoutes setting defaults to true, which means your /api/mcp route forwards requests to Shopify's hosted Storefront MCP without any server code on your end. Your storefront becomes a valid MCP endpoint the moment you ship the Hydrogen 2026.1.4 release.
The tools that endpoint exposes:
search_catalogfor free-text product discovery with category and price filterslookup_catalogfor retrieving up to 10 products or variants by IDget_productfor a single product with variant selection metadatasearch_shop_policies_and_faqsfor return windows, shipping policies, sizing guides, and any FAQ content stored in your shopget_cartandupdate_cartfor cart construction and the checkout URL handoff
The search_catalog, lookup_catalog, and get_product tools live at https://{shop}.myshopify.com/api/ucp/mcp because they use the Universal Commerce Protocol surface for catalog queries. Cart and policy tools sit at https://{shop}.myshopify.com/api/mcp. Shopify documents these as a single Storefront MCP product with two endpoint paths under the hood.
There is one critical operator-level reality the protocol cannot solve for you: the AI agents calling your endpoint will only sell well if your product data is structured for them. Natural-language titles ("Organic Cotton Sleep Mask, Blackout, Adjustable Strap") outperform brand-collection titles ("The Luna Collection, Midnight"). Complete product fields (Google Product Category, availability, full variant data) outperform sparse listings. Crawler access for GPTBot, ClaudeBot, and PerplexityBot in robots.txt is the precondition for any of this traffic to find you in the first place. AI-driven traffic to merchant stores is up 8x year-over-year since January 2025. The Storefront MCP is where that traffic converts, but only if your catalog speaks the agents' language.
We are publishing a dedicated spoke on hydrogen storefront mcp next month. For now, the takeaway: if you are not running Hydrogen, the Storefront MCP is not your problem this quarter. If you are, audit your product data before you celebrate the protocol shipping.
Shopify AI Toolkit vs. Sidekick vs. Third-Party MCPs
There are three "AI on Shopify" surfaces with overlapping names, different audiences, and very different capabilities. People conflate them in support threads daily. Here is the honest disambiguation.
Shopify Sidekick is the in-admin AI assistant Shopify includes free on every plan. It runs on Claude Sonnet 4.5 inside the merchant admin. It is conversational. It is built for non-technical merchants who want to ask "how did my Tuesday do?" or "duplicate this product and change the color." Sidekick is excellent at analytics queries, light theme adjustments, and store-context Q&A. It does not run inside your IDE, it does not validate GraphQL, and it does not execute bulk operations or theme deploys.
Shopify AI Toolkit (Dev MCP + Storefront MCP) is developer infrastructure. It connects Claude Code, Cursor, VS Code, Gemini CLI, and Codex to Shopify's APIs and documentation. It validates code. It executes mutations through the Shopify CLI. It is built for technical operators, agencies, freelancers, and developers managing one or many stores. It does not provide conversational analytics. It does not show you a sales graph. It runs your store the way an engineer runs a store.
Third-party community Shopify MCP servers (the most prominent being GeLi2001/shopify-mcp, still ranking at #5 on Google for shopify mcp) predate the official toolkit. They still work and continue shipping features the official toolkit does not (richer admin endpoints, built-in audit logs, draft mode). The trade-off is maintenance: when Shopify updates their API, community servers break until a maintainer pushes a fix. The official toolkit ships on the platform's release cadence.
A reasonable mental model: Sidekick is the merchant assistant, the AI Toolkit is the developer infrastructure, and community MCPs are the gap-fillers. Most stores need one of these, not all three. If your operator has terminal access, the AI Toolkit is the answer. For broader MCP server inventory, our 50+ MCP servers guide walks the full landscape.
Wiring Shopify to the Rest of Your Stack
Three vendors shipped official MCPs within a 21-day window: Shopify on April 9, Meta on April 29, and Higgsfield on April 30, 2026. Run them together inside Claude Code and you have the full ecommerce operator stack: creative production, paid distribution, store control. Higgsfield generates the assets. Meta runs paid distribution and reports performance. Shopify executes the store-side response (price changes, inventory shifts, theme tweaks, retention triggers). Claude Code stitches them together because all three speak MCP.
The cost is context. Running three MCP servers simultaneously can balloon Claude's session to 12,000+ tokens before any user prompt lands. This is what MCP Tool Search solves: it loads tool definitions on-demand, dropping the same three-MCP setup to roughly 600 tokens of permanent context. Enable it the day you wire your second MCP.
For the Meta side of the stack, our companion pillar Meta CLI and Meta MCP covers the install, the audience and creative endpoints, and the diagnostic patterns we use for cross-channel performance. For the creative side, Higgsfield MCP walks the prompt patterns, the Soul ID character training surface, and the production cadence we use for ad creative at scale.
The Shopify MCP gives Claude Code hands on your store. The Shopify Kit gives Claude Code judgment: 180+ files of operator playbooks across CRO, paid media, retention, SEO, ops, and architecture, 24 paid-ads patterns, 31 SEO files, 8 named playbooks ranging from the 90-Day Audit Sequence to the Quick Wins Sprint, and a _brand-template/ that turns the toolkit's hands into a structured engagement framework. The toolkit handles execution; the kit handles the strategy that tells execution what to do. That combination is what replaces a $5,000 to $15,000 monthly agency retainer with $199 and a Claude Code session.
April 2026 is the inflection point. Three official vendor MCPs shipped in 21 days, and stores that wire all three together are about to pull ahead of stores that treat them as separate experiments. The infrastructure is shipped. The white space is in the operator playbooks that connect them.
Last updated on
