| 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
- 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).
- Act — Call the narrowest tool. Prefer
shopify_search_products over
pulling the whole catalog. Prefer shopify_get_product for detail pages.
- 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).
