Shopify

The installed shopify command wraps Shopify's official MCP server. It is not the Shopify CLI from npm; the only verbs are the four below. Tool names and schemas come from shopify list-tools, never from memory — other Shopify connectors expose tools this one does not.

shopify status
shopify authorize-url
shopify list-tools
shopify call-tool --name <tool-name> --arguments-json '<JSON object>'

Connecting

1. shopify status. If a store is connected, go straight to work.
2. Otherwise shopify authorize-url and share only the returned connect_url with the user. Nothing else in that response is for them.
3. When they say they're done, shopify status, then call-tool --name get-shop-info to confirm which store is connected.

Before a store is connected, search_docs_chunks (searches https://shopify.dev), validate_graphql_codeblocks, find-mock-shop-catalogs, generate-domain-names, and generate-business-names work. get-storefront-generation is usable only with a generationUUID created by Shopify's storefront-generation widget; claim-storefront-preview is a widget callback and must not be called directly. Every other tool, including catalog import, needs a store. Do not ask someone to connect merely to explore sample catalogs, names, domains, or documentation.

Sample catalogs

When someone is starting a store, offer relevant mock.shop sample catalogs before asking them to connect:

1. Call find-mock-shop-catalogs with what they sell, in their own words. If they have not said, ask that one question first.
2. Present the best matches with their descriptions, product and collection counts, currency, and storefrontUrl. Clearly label each link as the source sample storefront, then ask which catalog they want.
3. Once connected, confirm before calling import-mock-shop-catalog with the selected subdomain.
4. Verify the destination records with search_products and search_collections, then report created, reused, skipped, unpublished, or partial results and any currency mismatch.

An import copies the first two collections and up to eight products from each, at most sixteen products, and publishes newly imported records to the Online Store. Repeating the same import is safe: it fills missing records and memberships without overwriting previously imported products or merchant edits. If Shopify reports partial: true, wait briefly and repeat the same import. These are sample records to edit or replace before launch, not supplier stock.

Users without a store

The same connect_url works for someone who has never used Shopify. Shopify's sign-in page lets them create an account and a new store, then returns them to the connection. Tell them this up front so they don't go create a store separately first. Once connected, offer a first-store sequence and take it one step at a time:

1. get-shop-info to learn the store's name, currency, and plan.
2. Import the sample catalog they selected, or use create-product for their own products (title, description, price, images by URL). Ask what they sell; don't invent a catalogue.
3. create-collection, then add-to-collection to group them.
4. If they track stock, call get-inventory-levels before set-inventory to resolve the inventory item, location, and current quantity.
5. create-discount for a launch promotion, only if they want one.

Business-name and domain results may include signupUrl links for starting a store. Use those for exploration; when the user is ready to connect Muse to their store, share the connector's connect_url instead.

Point them at the Shopify admin (the domain from get-shop-info) for anything this server doesn't cover: themes, checkout, payments, shipping, and connecting or buying domains.

Common tasks

Task	Tools
Store details	get-shop-info
Business names and available domains	generate-business-names, generate-domain-names
Sample catalogs	find-mock-shop-catalogs, then import-mock-shop-catalog with the selected subdomain; this imports catalog data, not storefront design
Storefront previews	get-storefront-generation only for a generation already created by Shopify's widget
Products	search_products, get-product, create-product, update-product, bulk-update-product-status
Collections	search_collections, get-collection, create-collection, update-collection, add-to-collection
Inventory	get-inventory-levels, set-inventory
Orders and customers	list-orders, get-order, list-customers
Discounts	create-discount
Reports and trends	run-analytics-query (ShopifyQL; the description has examples)
Anything else in Admin	graphql_schema → validate_graphql_codeblocks → graphql_query or graphql_mutation, in that order, every time
How Shopify works	search_docs_chunks
Another store	switch-shop, then get-shop-info

Rules

• Authenticated commands refresh an expired access token automatically. Do not tell the user to disconnect and reconnect for ordinary expiry. If Shopify reports that the refresh grant was revoked or reauthorization is required, run shopify authorize-url; do not require a disconnect first unless the returned result explicitly says it is necessary.
• Inspect the returned result as well as the command status: Shopify can report a tool-level failure inside a successful MCP response.
• Confirm with the user before any tool that writes: create, update, set, bulk, discounts, catalog import, preview claims, graphql_mutation. Catalog import publishes sample products and collections to the Online Store; report partial imports and currency mismatches (prices are copied without conversion).
• A catalog import does not change the store name, theme, navigation, homepage sections, or pre-existing products. The storefrontUrl returned by find-mock-shop-catalogs previews the source mock catalog, not the destination store after import. Never say the destination storefront will look like that preview or offer its homepage as proof. After importing, verify the new records with search_products and search_collections, then report that the merchant must configure their theme in Shopify Admin if they want the homepage to feature the imported catalog.
• switch-shop must be followed by another tool call (the requested action, or get-shop-info) to finish the switch.
• get-storefront-generation only polls a generationUUID already created by Shopify's storefront-generation widget; it cannot start a generation or alter an existing store. claim-storefront-preview is called only by that widget, never directly by the model. Neither tool applies a mock catalog's theme to a connected store.
• Muse shows structured data, not Shopify's widgets. Summarize results in the reply; don't refer to a card, chart, or preview the user can't see.