mcp-store-tools

An MCP server that turns any AI assistant into a shopping assistant and catalog auditor for a Shopify store: it answers from the live catalog, pages, and policies, recommends products, hands the shopper a verified checkout link, and audits the whole catalog for the merchant in one call. It is read-only by construction: it uses a Storefront API token, which can only see what the public storefront already shows.

Claude Desktop / any MCP client ──stdio──► mcp-store-tools ──HTTPS──► Shopify Storefront API
                                             13 read-only tools          (public token)

Ask your agent "do you have this hoodie in black, size M?", "what's on sale?", "how much is it in pounds?", "compare these two", "what goes with it?", "do you ship to Germany?", "what size should I get?", "send me a link to buy two", or "audit our catalog for listing problems" and it answers from the live store, with links.

What makes it different:

• Cart links that cannot be wrong. build_cart_link checks every variant belongs to the product and is in stock before returning a Shopify cart permalink, so a model cannot send a shopper to a guessed or sold-out item. Nothing is written to the store.

• A whole-catalog audit in one tool call. audit_catalog walks up to 5,000 products in the server and returns counts, percentages, examples, and the top three fixes, instead of the model paging through the catalog and burning tokens.

• Size and colour that are really in stock. search_products with options: {"Size": "M", "Color": "Black"} checks real variants (many stores ignore Shopify's option filter) and returns the matching variants.

• "Only 3 left". With the token's inventory permission, variants carry quantity_available; without it the server detects the missing scope once and carries on. Items whose stock is not tracked read as unknown, never a misleading "0 left".

• Deals and local prices. find_deals ranks sale items by discount; every product tool takes a shopper country, so prices and availability follow that market (Shopify Markets).

• Search that does not miss. Price and stock filters are enforced on every result, and when Shopify's search index comes back empty (common on new stores) it falls back to keyword matching for products and pages.

• Safe with untrusted store text. HTML is stripped, every field is capped, and each tool tells the model that store content is data, not instructions.

Try it in 30 seconds

No Shopify account needed: --demo uses Shopify's public sample store.

claude mcp add store-demo -- uvx --from git+https://github.com/thealirazadev/mcp-store-tools mcp-store-tools --demo

Then ask Claude Code: "What's the cheapest thing in the store, and what's the refund policy?"

Related MCP server: Shopify MCP Server

Tools

Every tool carries the MCP readOnlyHint, and failures come back as tool errors the model can relay ("the store is busy, try again shortly"), never stack traces or the token.

Resources

The same read-only data as attachable context: store://info, store://collections, and store://policies/{kind} (refund, shipping, privacy, terms, subscription).

Prompts

Clients that show MCP prompts (Claude Desktop, VS Code, Cursor) get three ready-made workflows: Audit the catalog (listing problems report for the merchant), Compare products, and Answer a policy question.

Setup

1. Install Shopify's free Headless sales channel on the store, open Headless > Create storefront > Storefront API, and copy the public access token. Its default permissions include product listings and content. (A trial store's storefront stays locked until a plan is chosen; a development store works.)

2. Install the server: uv tool install git+https://github.com/thealirazadev/mcp-store-tools (or run it without installing via uvx --from git+https://github.com/thealirazadev/mcp-store-tools mcp-store-tools).

Claude Desktop

Add this to claude_desktop_config.json (Settings > Developer > Edit Config), then restart:

{
  "mcpServers": {
    "my-store": {
      "command": "mcp-store-tools",
      "env": {
        "SHOPIFY_STORE_DOMAIN": "your-store.myshopify.com",
        "SHOPIFY_STOREFRONT_TOKEN": "your-storefront-token"
      }
    }
  }
}

Claude Code

claude mcp add my-store --env SHOPIFY_STORE_DOMAIN=your-store.myshopify.com \
  --env SHOPIFY_STOREFRONT_TOKEN=your-storefront-token -- mcp-store-tools

Configuration

Policies and collections are cached for five minutes; products, prices, and stock are always fetched live. Shopify throttling is retried with backoff, honouring Retry-After.

Cursor, VS Code, Windsurf, Codex, Gemini CLI

Config snippets for each are in skill/shopify-store-assistant/reference/setup.md.

Hosting over HTTP

--transport http serves MCP Streamable HTTP at /mcp (default 127.0.0.1:8000; --host, --port, or PORT). The Docker image runs in this mode:

docker build -t mcp-store-tools .
docker run -p 8000:8000 -e SHOPIFY_STORE_DOMAIN=your-store.myshopify.com \
  -e SHOPIFY_STOREFRONT_TOKEN=your-storefront-token mcp-store-tools
claude mcp add --transport http my-store http://localhost:8000/mcp

GET /healthz answers without authentication (the Docker image uses it as its health check). Each client address may make MCP_RATE_LIMIT requests per minute (default 120, 0 turns it off); beyond that the server answers 429 with Retry-After, protecting the store's Storefront API quota.

Set MCP_AUTH_TOKEN to require Authorization: Bearer <token> on every request (add --header "Authorization: Bearer <token>" to claude mcp add). Read SECURITY.md before exposing the server beyond localhost.

Agent skill

skill/shopify-store-assistant is an agent skill that teaches the model how to use the tools well: which tool answers which question, to quote only prices and policies the store returned, to link its sources, and how to run a full catalog audit (missing descriptions, sold-out products, suspicious price ranges, duplicate titles) as a report for the merchant.

• Claude Code: copy the folder to ~/.claude/skills/ (or .claude/skills/ in a project).

• Other agents that read SKILL.md: copy it to the agent's skills folder.

• Each release attaches the folder as shopify-store-assistant-skill.zip.

Safety

Product descriptions and policies are written by merchants and suppliers, so the server treats them as untrusted:

• HTML is stripped to plain text (script and style contents are dropped), so markup cannot hide instructions.

• Every text field is length-capped, so one product cannot flood the model's context.

• Tool descriptions and the server instructions tell the model the content is data to quote, not instructions to follow.

The design reasoning is in docs/decisions.md; the security model and how to report a vulnerability are in SECURITY.md.

Development

uv sync
uv run ruff check . && uv run ruff format --check . && uv run mypy && uv run pytest

The default tests never call Shopify: the GraphQL client runs against httpx.MockTransport, the server tests connect a real MCP client in-process to check the tool list, schemas, and error results a client actually sees, and a skill test checks SKILL.md names exactly the served tools.

MCP_STORE_TOOLS_LIVE=1 uv run pytest tests/test_live.py starts the server in demo mode over stdio and over HTTP and calls the tools against the real Storefront API. CI runs it weekly, and builds the Docker image on every push. With SHOPIFY_STORE_DOMAIN and SHOPIFY_STOREFRONT_TOKEN also set (a development store with test data), it additionally checks a real store and the wrong-token error; CI reads them from the SHOPIFY_STORE_DOMAIN variable and SHOPIFY_STOREFRONT_TOKEN secret. evals/ runs real shopper and merchant questions through a model (Claude Code, headless) and checks the tools it picks: 10/10 on the latest run. See CONTRIBUTING.md.

The demo image is regenerated from real output with uv run python scripts/render_demo.py (it runs examples/demo.py against the sample store).

Releases: bump version in pyproject.toml, add a CHANGELOG.md entry, and push a v* tag.

License

MIT