Shopify MCP Server — ShopManager AI (Free, Open Source)

Connect Claude, ChatGPT, Cursor, Codex, VS Code — or any MCP client — to a Shopify store, and let the assistant read the store the way you read the admin, and read the theme the way you read the code.

122 tools. Self-hosted. Apache-2.0. Free forever.

Don't want to install anything?

Use the same free tools hosted, with no setup: shopmanagerai.com/free

Connect a store in a browser, paste one line into your AI client, done. No server, no Node, no terminal. This repository is for people who would rather run it themselves.

Contents

• What it does

• Free is read-only on your theme

• Try it in two minutes — no Shopify store needed

• Connect your AI client

• Tutorial: your first session

• Run it against a real store

• What's included

• Free vs Pro

• Configuration

• Troubleshooting

• FAQ

Related MCP server: Shopify MCP Server

What it does

An AI client on its own cannot see your store. It guesses at your theme, invents section names, and cannot tell you which snippet renders the cart drawer. This server gives it the real thing over the Model Context Protocol:

• Read the theme like source code. Full file tree by role, every section and block schema, Liquid parsing and validation, grep-style search across the theme, and reference tracing — which templates actually render this snippet?

• Run Theme Check and get each issue explained, not just listed.

• Read the catalogue and content: products, variants, collections, pages, blogs, articles, menus, metafields, metaobjects, media, redirects.

• Read store configuration: markets, locales, translations, price lists, discounts, inventory, locations, webhooks, pixels, script tags, functions, checkout profiles.

• Diagnose the connection: which scopes are granted, which capabilities are missing, and exactly what to do about each one.

• Remember things between sessions with saved memories and custom skills.

Typical uses: understanding a theme you inherited, auditing a store before a migration, answering "where does this come from?" without opening ten admin tabs, and giving an AI assistant accurate context before you ask it to write any code.

Free is read-only on your theme

This is the guarantee the build is designed around, and it is verified on every release rather than promised in prose:

• No tool in this repository writes a theme file. Not a section, not a snippet, not settings_data.json. The assistant can read, search, diff and explain your theme. It cannot edit it.

• The handful of tools that do write, write to this server's own state — saved memories, skills, snapshots, operation records — with two exceptions that reach Shopify: shopify.auth.disconnect and commerce.settings.storefront_password.

• Every call is recorded in the operation ledger, so you can see afterwards exactly what ran. The two destructive tools, commerce.memory.delete and commerce.skills.delete, delete data this server stores — never store data.

CI runs scripts/assert-free-only.mjs against the registry the server actually builds. If a tool that writes a theme file ever appears here, the build fails.

Try it in two minutes — no Shopify store needed

Demo mode serves a complete fake store, so you can see every tool work before connecting anything real. Requires Node 22+ and pnpm.

git clone https://github.com/shopmanagerai/shopify-mcp.git
cd shopify-mcp
pnpm install
pnpm build
cp .env.example .env

Set one line in .env:

SHOPMANAGER_DEMO=1

Start it:

pnpm start

You will see:

======================================================================
 ShopManager AI, DEMO MODE
 Serving a single fake store: demo.myshopify.com
 Admin UI:  http://localhost:3000/admin?shop=demo.myshopify.com
 MCP URL:   http://localhost:3000/mcp/demo.myshopify.com
======================================================================

In demo mode the bearer token is the fixed string cp_demo. Add it to Claude Code:

claude mcp add --transport http shopmanager http://localhost:3000/mcp/demo.myshopify.com --header "Authorization: Bearer cp_demo"

Then ask your assistant: "Inspect this Shopify store and tell me the store name, active theme, and number of products." If it answers, everything works.

Connect your AI client

Every client talks to the same URL: http://<host>/mcp/<shop-handle> (Streamable HTTP). Replace <TOKEN> with cp_demo in demo mode, or with the cp_ token you create in the Connect screen of the admin UI.

Claude Code

claude mcp add --transport http shopmanager http://localhost:3000/mcp/demo.myshopify.com --header "Authorization: Bearer <TOKEN>"

Cursor — ~/.cursor/mcp.json

{ "mcpServers": { "shopmanager": { "url": "http://localhost:3000/mcp/demo.myshopify.com", "headers": { "Authorization": "Bearer <TOKEN>" } } } }

VS Code — .vscode/mcp.json

{ "servers": { "shopmanager": { "type": "http", "url": "http://localhost:3000/mcp/demo.myshopify.com", "headers": { "Authorization": "Bearer <TOKEN>" } } } }

Codex — ~/.codex/config.toml

[mcp_servers.shopmanager]
url = "http://localhost:3000/mcp/demo.myshopify.com"
http_headers = { Authorization = "Bearer <TOKEN>" }

Any other client that speaks Streamable HTTP works too. Full notes, including the flat-vs-meta tool surface, are in docs/mcp-clients.md.

Keeping the client's context small

By default the server advertises three meta-tools — discover-tools, get-schema, execute-tool — instead of all 122, so your context window is not spent on a tool catalogue. Append ?surface=flat to the URL if you would rather the client see every tool directly.

Tutorial: your first session

Run these in order the first time you connect a store. They are all read-only.

1. Confirm you are pointed at the right store

Inspect my Shopify store and tell me the store name, the active theme and the number of products. Do not make any changes.

The store name in the reply is the check. If it is not the store you expected, stop and fix the connection before going further.

2. Find out what the connection can actually do

List the ShopManager AI tools available for this store, grouped by whether they are available, plan-gated, missing a scope, or missing a capability. For anything unavailable, show the exact reason.

This is faster than reading logs when theme tools are unexpectedly absent. See Troubleshooting for what the reasons mean.

3. Get oriented in the theme

Show me the architecture of the active theme: templates, sections, blocks, snippets and assets, with file counts per group.

4. Ask a question you could not answer from the admin

Which templates and sections actually render snippets/product-card.liquid? Show the reference chain.

This is the thing a plain AI client cannot do. It traces real render and include calls across the theme.

5. Check the theme for real problems

Run Theme Check on the active theme, summarise the issues by severity, then explain the three most serious ones and what causes them.

6. Look for content gaps

List my collections and pages, and tell me which ones have no description or no SEO title.

7. Remember what you learned

Save a memory: this store uses a Dawn-based theme, the cart drawer lives in snippets/cart-drawer.liquid, and product cards are rendered from snippets/product-card.liquid.

Memories persist across sessions, so the next conversation starts informed.

More prompts, grouped by task and risk level, are in the prompt library.

Run it against a real store

Demo mode needs nothing. A real store needs a Shopify app to authenticate against.

1. Create a custom app in your Shopify Partner Dashboard and copy its client ID and secret.

2. Fill in .env:

   SHOPMANAGER_DEMO=0
   SHOPIFY_CLIENT_ID=your-client-id
   SHOPIFY_CLIENT_SECRET=your-client-secret
   APP_URL=https://your-public-url        # must be reachable by Shopify

   SHOPIFY_SCOPES in .env.example already lists what the tools need. The server tells you which scope is missing when one is.

3. Start the server and open http://<APP_URL>/admin?shop=<your-store>.myshopify.com.

4. Complete the install in the Shopify admin when prompted.

5. Enter your Theme Access password in the admin UI. Theme tools read files through Shopify's Theme Access proxy and will report capability_missing until this is set.

6. Create a token in the Connect screen, and use it as <TOKEN> above.

APP_URL must be publicly reachable for the OAuth callback — a tunnel such as cloudflared or ngrok is fine for development.

What's included

All 122 tools, by area:

The machine-readable list of every tool, with input and output schemas, scopes and risk class, is tools-manifest.json.

Use Shopify's Dev MCP alongside

Shopify's own open-source Dev MCP (documentation search, GraphQL schema introspection, validate_theme) is complementary — this server does not duplicate documentation lookup. Install both.

Free vs Pro

Everything in this repository is Free and always will be. Free reads; it does not change the store.

Pro is a hosted service at shopmanagerai.com. It is not in this repository and cannot be unlocked from it — see free vs pro and pricing.

Configuration

The settings that matter most. Everything else is documented inline in .env.example.

Storage is SQLite by default; set DATABASE_URL to a postgres:// URL to use Postgres instead.

Troubleshooting

Start here. Ask your assistant to run shopify.auth.doctor, or:

Diagnose this connection and tell me exactly what is wrong and how to fix it.

It returns a checklist of issues with the fix for each.

Health endpoints: /healthz, /readyz and Prometheus metrics at /metrics.

FAQ

Is this really free? Yes. Apache-2.0, no key, no account, no phone-home. Run it forever.

Do I have to self-host to use the free tools? No. The same free tools run hosted at shopmanagerai.com/free with no installation. This repository is for people who want to own the deployment.

Can the AI break my store? Not through this build. No tool here writes a theme file, and the tools that write at all write to the server's own state. See the guarantee.

Does it work with ChatGPT / Claude / Cursor / Codex / VS Code? Any client that speaks MCP over Streamable HTTP. Configurations for the common ones are above.

Which Shopify API version does it use? 2026-07 by default, set by SHOPIFY_API_VERSION. Ask for commerce.api.capabilities to see what the current version supports.

Can I run it without a Shopify store? Yes — demo mode serves a complete fake store.

Can I contribute? Yes, though this repository is generated from a private monorepo that holds both the Free and Pro tools. Changes land there first and reappear here on the next release, so please open an issue before a large change rather than writing it twice.

How this repository relates to the hosted service

A release script cuts every Pro tool definition out of the private monorepo and publishes the result, so the Free code here is the same code the hosted service runs for Free users. The git history here is release history, not development history.

Licence

Apache-2.0 — see LICENSE. The ShopManager AI name and logo are not covered by it; see TRADEMARKS.md.