# 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](https://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](#what-it-does)
- [Free is read-only on your theme](#free-is-read-only-on-your-theme)
- [Try it in two minutes — no Shopify store needed](#try-it-in-two-minutes--no-shopify-store-needed)
- [Connect your AI client](#connect-your-ai-client)
- [Tutorial: your first session](#tutorial-your-first-session)
- [Run it against a real store](#run-it-against-a-real-store)
- [What's included](#whats-included)
- [Free vs Pro](#free-vs-pro)
- [Configuration](#configuration)
- [Troubleshooting](#troubleshooting)
- [FAQ](#faq)

---

## 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](https://modelcontextprotocol.io):

- **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`](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**.

```bash
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`:

```bash
SHOPMANAGER_DEMO=1
```

Start it:

```bash
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:

```bash
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**

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

**Cursor** — `~/.cursor/mcp.json`

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

**VS Code** — `.vscode/mcp.json`

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

**Codex** — `~/.codex/config.toml`

```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](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](#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](https://shopmanagerai.com/resources/shopify-ai-prompts/).

## 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`**:

   ```bash
   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:

| Area | Tools | Examples |
| --- | ---: | --- |
| Theme inspection, files, Theme Check | 23 | `shopify.theme.architecture`, `shopify.theme.find_reference`, `shopify.theme.file.diff`, `shopify.theme_check.run` |
| Catalogue and content reads | 19 | `shopify.products.list`, `shopify.collection.get`, `shopify.blogs.list`, `shopify.metafields.list` |
| Store configuration and commerce reads | 19 | `shopify.markets.list`, `shopify.translations.list`, `shopify.inventory.get`, `shopify.webhooks.list` |
| System, health and diagnostics | 17 | `commerce.health`, `commerce.capabilities`, `commerce.diagnostics.permissions` |
| Change planning, ledger, export | 11 | `commerce.change.plan`, `commerce.operations.list`, `commerce.export` |
| Memory and skills | 11 | `commerce.memory.save`, `commerce.skills.write` |
| Sections, blocks, templates, Liquid | 9 | `shopify.section.schema`, `shopify.template.inspect`, `shopify.liquid.validate` |
| Auth and capability probes | 7 | `shopify.auth.doctor`, `shopify.store.capabilities` |
| Snapshots | 6 | `commerce.snapshot.create`, `commerce.snapshot.diff`, `commerce.rollback.plan` |

The machine-readable list of every tool, with input and output schemas, scopes
and risk class, is [`tools-manifest.json`](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.

| | Free (this repo, or hosted) | Pro (hosted) |
| --- | --- | --- |
| Read theme, catalogue, content, config | ✅ | ✅ |
| Theme Check, Liquid validation, reference tracing | ✅ | ✅ |
| Memories, skills, snapshots, ledger | ✅ | ✅ |
| Edit theme files, publish themes | ❌ | ✅ |
| Write products, collections, pages, articles, menus | ❌ | ✅ |
| SEO audits and bulk SEO optimisation | ❌ | ✅ |
| Design generation, page building, redesign | ❌ | ✅ |
| Screenshots and visual QA | ❌ | ✅ |
| Store-wide audit and orchestration | ❌ | ✅ |

Pro is a hosted service at [shopmanagerai.com](https://shopmanagerai.com). It is
not in this repository and cannot be unlocked from it — see
[free vs pro](https://shopmanagerai.com/free-vs-pro/) and
[pricing](https://shopmanagerai.com/pricing/).

## Configuration

The settings that matter most. Everything else is documented inline in
[`.env.example`](.env.example).

| Variable | What it does |
| --- | --- |
| `SHOPMANAGER_DEMO` | `1` serves a fake store and needs no Shopify credentials |
| `PORT` | HTTP port, default `3000` |
| `APP_URL` | Public URL of this server; used for the OAuth callback |
| `DATA_DIR` | Where the SQLite database and blobs live, default `./data` |
| `SHOPIFY_CLIENT_ID` / `SHOPIFY_CLIENT_SECRET` | Your custom app's credentials |
| `SHOPIFY_SCOPES` | Scopes requested at install |
| `SHOPMANAGER_MASTER_KEY` | 32 random bytes, base64, for secret encryption. Generated in dev if unset — always set it in production |
| `MCP_RATE_LIMIT_PER_MIN` | Requests per minute per credential, default `600` |

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.

| Symptom | Cause | Fix |
| --- | --- | --- |
| Theme tools report `capability_missing` | No Theme Access password stored | Enter it in the admin UI. Reinstalling the app clears it |
| A tool reports `scope_missing` | The app was installed without that scope | Update `SHOPIFY_SCOPES`, reinstall, and re-approve in the Shopify admin |
| A tool reports `pro_required` | It is a Pro tool | Not available in this build, by design |
| `401` with a `WWW-Authenticate` header | Missing or wrong bearer token | Check the `Authorization: Bearer <TOKEN>` header |
| The assistant cannot see any tools | Wrong URL or unknown shop | The path is `/mcp/<shop>`; a bare handle gets `.myshopify.com` appended, and the shop must already be connected |

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](https://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](#free-is-read-only-on-your-theme).

**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](#connect-your-ai-client).

**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](#try-it-in-two-minutes--no-shopify-store-needed) 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](LICENSE). The ShopManager AI name and logo are not
covered by it; see [TRADEMARKS.md](TRADEMARKS.md).