shopify-mcp

name

shopify-mcp

description

Use Shopify Storefront MCP tools to search catalogs, inspect products, read and mutate carts, fetch policies, and describe shops across any MSApps / OpsAgents client store — multi-tenant, no shop hardcoded. Trigger on: "shopify", "storefront", "myshopify", "cart", "checkout", "products", "catalog", "collection", "shipping policy", "refund policy", "client store", "merchant", or any task that needs live data from a Shopify merchant. Also use when the user wants to prototype a conversational shopping flow, a recommendation agent, or a customer-support bot over a Shopify store.

Shopify MCP — multi-tenant storefront operator

Use this skill whenever Claude needs to act on a Shopify store through the opsagent-shopify MCP server. Prefer these tools over raw fetch calls or the generic apify-scraping skill — they are tokened, rate-aware, and multi-tenant.

When to trigger

• "What's in <client-handle>'s catalog right now?"
• "Find products in shop X under $50 that contain 'linen'."
• "Build me a cart with three of variant ID ..."
• "Read the shipping policy of foo.myshopify.com."
• "Describe the storefront of this shop before we swap the theme."
• "Why is selectModel() returning undefined on the product page of <shop>?" → call shopify_describe_theme first to confirm which theme + version is live before diving into theme JS.

Mental model

One install, every store. Each tool takes an optional shop argument of the form <handle>.myshopify.com. If omitted, the server falls back to SHOPIFY_DEFAULT_SHOP (set per-client in the MCP config). Never hardcode a shop inside the skill — pass it explicitly when the user mentions one.

Two backends, one surface:

• Public catalog + cart ops go to Shopify's Storefront MCP endpoint (https://{shop}/api/mcp). No token. Tools: shopify_search_products, shopify_get_cart, shopify_update_cart.
• Richer read ops (products by handle, policies, collections, shop metadata) go to Storefront GraphQL. Needs SHOPIFY_STOREFRONT_TOKEN.

If a GraphQL tool errors with "Storefront GraphQL requires a token," surface that to the user and ask them to paste one into the plugin config — don't silently degrade.

Plan → Act → Verify

1. Plan — Identify the shop and the intent (read vs cart-mutation vs checkout-mutation). Read ops are cheap; cart mutations should be confirmed with the user if the cart is real (not a throwaway test cart).
2. Act — Call the narrowest tool. Prefer shopify_search_products over pulling the whole catalog. Prefer shopify_get_product for detail pages.
3. Verify — For cart mutations, re-fetch with shopify_get_cart and show the resulting line items. For checkout starts, return the URL and tell the user what will happen if they open it.

Tools at a glance

Tool	Class	Token?	Purpose
shopify_search_products	read	no	Search catalog by free text.
shopify_get_product	read	yes	Product detail by handle.
shopify_get_cart	read	no	Cart state by ID.
shopify_update_cart	cart-mutation	no	Create/add/update/remove lines.
shopify_get_policies	read	yes	Shipping / refund / privacy / terms.
shopify_list_collections	read	yes	Category pages.
shopify_describe_theme	read	yes	Shop + brand + domain metadata.

Failure modes to watch

• No shop configured → "No shop configured. Pass shop argument or set SHOPIFY_DEFAULT_SHOP." Ask the user which store, don't guess.
• Invalid domain format → reject anything that isn't <handle>.myshopify.com. Custom vanity domains (e.g. <brand>.com) need to be resolved to their myshopify.com canonical form first.
• GraphQL 401/403 → Storefront token expired or scoped too narrow. Regenerate in Admin → Sales channels → Headless.
• Rate limits → Storefront API allows ~60 RPM per shop. If bursting, chunk and backoff; never retry blindly.

Handoff to related skills

• For theme changes (Symmetry install, customizing Liquid), invoke the symmetry-install skill in this same plugin.
• For Liquid code edits, defer to the shopify-liquid reference skill.
• For the app side (OAuth install on a merchant's admin, webhook registration), the opsagent-shopify-mcp repo README has the CLI flow.

SOSA notes

• Supervised — cart and checkout mutations must be confirmed with the user when they touch a real customer cart. Read ops are unsupervised.
• Secured — the Storefront token is sensitive and per-shop; never log it or include it in tool outputs.
• Agents — this skill owns Shopify-facing data ops only. It does NOT touch theme files, Liquid, billing, or Partner API — those are other skills or the Admin API (not this server).