@curless/shopify-storefront

A Shopify store as an MCP connector for AI assistants (Claude, ChatGPT and any other MCP host). A buyer browses the catalogue, picks options, builds a cart and is handed a link to the merchant's own Shopify checkout — the money and the order stay in the merchant's Shopify. Results render as an MCP Apps card.

One server, driven by a config file: the merchant's name, tool names, the words for what they sell and the shop wiring all come from config.json, so a second merchant is a second file, not a fork.

npm install -g @curless/shopify-storefront
STOREFRONT_CONFIG=./config.json \
STOREFRONT_SHOPIFY_CLIENT_ID=… STOREFRONT_SHOPIFY_CLIENT_SECRET=… \
curless-shopify-storefront

Deployed on Node 22. It listens on PORT (default 8090) and expects a TLS-terminating reverse proxy in front of it that sets X-Forwarded-For.

The tools

Named from the config's naming.prefix and nouns — with prefix acme and the default noun product:

| Tool | What it does | |---|---| | list_acme_products | The catalogue as a card; optional query, maxPrice, limit. | | get_acme_product | One product: options, prices, which combinations are in stock. | | add_to_acme_cart / view_acme_cart / clear_acme_cart | A cart kept by this server, in memory, per conversation. Nothing reaches Shopify until the buyer pays. | | get_acme_checkout_link | A Shopify cart permalink for one variant, or for the whole cart. Creates nothing. | | lookup_acme_order | One order, given its order number and the email it was placed with. | | get_acme_store_policies | The shop's published returns, shipping, privacy and terms pages. | | check_acme_checkout_status | For the card only: whether the checkout it opened has been paid. |

Configuration

config.json holds everything that identifies the merchant; the environment holds only secrets and machine settings.

{
  "id": "acme",
  "server": { "name": "acme-shop", "title": "Acme", "websiteUrl": "https://acme.example" },
  "naming": { "prefix": "acme" },
  "shopify": { "mode": "env", "shopDomain": "acme.myshopify.com" },
  "urls": { "appUrl": "https://mcp.acme.example" },
  "legal": {
    "operatorContact": "[email protected]",
    "merchantContact": "[email protected]",
    "updated": "1 October 2026"
  }
}

• shopify.mode: "env" serves one shop, installed once through the app's OAuth flow (/auth/install); the token is stored at shopify.tokenPath (default /app/data/<id>-token.json — keep it on a volume). "oauth-install" is the multi-shop form, where the shop is whoever installed the app and the connector URL is /s/<shop>/mcp.
• urls.appUrl is the app URL registered with Shopify; urls.publicUrl, when set, is the hostname buyers connect to.
• legal.* fills the /privacy, /terms and /docs pages that directory reviewers read. Missing contacts do not fail the boot, but leave gaps there.

| env | | |---|---| | STOREFRONT_CONFIG | Path to config.json (required). | | STOREFRONT_SHOPIFY_CLIENT_ID / _CLIENT_SECRET | The Shopify app's credentials; the secret also signs the OAuth callback and webhooks. | | STOREFRONT_SHOPIFY_ADMIN_TOKEN | Optional: an existing Admin API token, skipping the install. | | PORT | Default 8090. | | CATALOG_REFRESH_MS | Default 300000 (5 minutes). A failed refresh keeps serving the last good catalogue. | | OPENAI_APPS_CHALLENGE_TOKENS | host=token,… — ChatGPT Apps domain verification. |

Endpoints

POST /mcp (and /) is the MCP endpoint (streamable HTTP, JSON responses). Alongside it: /healthz, /docs, /privacy, /terms, /icon.png, /logo.png, /img (the card's image proxy for Shopify's CDN), and the Shopify install routes /auth/install, /auth/callback, /webhooks/shopify.

What it guards

• No write access to the shop is needed for selling. Checkout is a Shopify link; no card number or payment token reaches this server.
• Order lookup needs the order number and the email together, answers a wrong email and a missing order alike, and pauses lookups after five misses in fifteen minutes for one order number, one email or one conversation (fifty for one network address, a hundred for the whole shop).
• Limits: 60 requests a minute per address, a 1 MB request body, bounded tool arguments.
• The merchant's own text (descriptions, policies) is stripped of control and invisible characters, length-capped and fenced before it reaches the assistant.

License

MIT