Shopify

Go to dev.shopify.com, open Apps, click Create app, choose Start from Dev Dashboard, name the app ShopMCP (or anything you like), then create it.

Open the app's Versions tab. Shopify requires at least one released version before the app can be installed. For the public ShopMCP install app, set the app URL to https://my.shop-mcp.app/api/integrations/shopify/public/start and the compliance webhook URL to https://my.shop-mcp.app/api/integrations/shopify/compliance. For a private same-organization fallback app, use a non-Shopify placeholder app URL. Choose the newest Webhooks API version, enter the comma-separated Admin API scopes below, then click Release.

These are the read scopes ShopMCP uses for ShopifyQL revenue and traffic analytics, products, orders, customers, inventory, fulfillments, content, discounts, locations, and shipping zones:

text
read_products,read_orders,read_draft_orders,read_fulfillments,read_assigned_fulfillment_orders,read_merchant_managed_fulfillment_orders,read_third_party_fulfillment_orders,read_customers,read_inventory,read_locations,read_returns,read_gift_cards,read_price_rules,read_discounts,read_content,read_files,read_online_store_pages,read_online_store_navigation,read_shipping,read_locales,read_metaobjects,read_metaobject_definitions,read_markets,read_reports,read_shopify_payments_payouts

Skip this step if you only want the assistant to read store data. If you want ShopMCP's mutating tools — updating products, adjusting / transferring inventory between locations, issuing refunds, creating draft orders / invoices / B2B quotes, completing draft orders into real orders, sending invoice emails, creating customer addresses, creating discounts and bulk-importing redeem codes, editing pages, managing metafields and tags, updating customer records, creating fulfillments, and triggering Shopify Flow workflows — add the matching write_* scopes to the same Dev Dashboard app version:

text
write_products,write_orders,write_draft_orders,write_fulfillments,write_assigned_fulfillment_orders,write_merchant_managed_fulfillment_orders,write_third_party_fulfillment_orders,write_customers,write_inventory,write_returns,write_gift_cards,write_price_rules,write_discounts,write_content,write_files,write_online_store_navigation,write_metaobjects,write_metaobject_definitions,write_markets

Each individual write tool also asks the assistant to confirm with you before firing, so you get a third layer of protection at the per-call level.

Sales-channel publication tools are advanced because Shopify can require publication access before the app version accepts the scopes. Only add these after Shopify enables publication access for your app, and only if you need publication-channel audits or publish/unpublish tools:

text
read_publications,write_publications

Do not add read_product_listings for ShopMCP. That older product-listing / feed scope is not required for the normal ShopMCP product tools and is the easiest stale scope to paste by mistake.

From the app's Home page in the Dev Dashboard, click Install app, select or create the store, then approve the requested scopes in Shopify admin. If you later release a new version with more scopes, Shopify does not apply the new scopes automatically; approve the scope update on the store before enabling matching tools.

After approving new scopes, return to Settings → Integrations → Shopifyand click the refresh action on the connected store row. ShopMCP will exchange the stored Client ID and Secret for a fresh token and record Shopify's latest approved scopes without requiring you to remove and re-add the connection.

If you're installing ShopMCP as a public Shopify app instead of bringing your own Dev Dashboard app, Shopify now expects public apps to use expiring offline tokens. ShopMCP's install callback stores the access-token expiry, refresh token, and refresh-token expiry so it can rotate tokens server-side without asking the merchant to reinstall.

If you connected an older ShopMCP public-app install before this rotation model, ShopMCP will migrate that store forward the next time it resolves tools for the workspace. Merchants should not need to reinstall just for this deadline.

Open the app's Settings page in the Dev Dashboard and copy the values in Credentials:Client ID and Secret. The secret usually starts with shpss_.

Open Settings → Integrations → Shopify and fill in:

• Store domain — your canonical myshopify domain, e.g. yourstore.myshopify.com. Custom / vanity domains don't work here; Shopify always serves the Admin API from the myshopify subdomain.
• Client ID — the value from the Dev Dashboard app's Settings → Credentials panel.
• Secret — the shpss_… secret from the same panel. Do not paste the atkn_… App automation token.
• Store nickname (optional) — useful when you connect more than one store, e.g. AU store / US store.

Hit Connect Shopify. ShopMCP requests a short-lived Admin API access token from Shopify, runs a quick GraphQL probe against your store, then encrypts and stores the client credentials so it can refresh the token automatically. You're done — Shopify tools appear in Claude Desktop / Cursor / ChatGPT on the next MCP session.

A workspace can hold as many Shopify stores as you like. Repeat steps 1–6 for each store, then label each connection so prompts can target the right shop by label, domain, shop name, or connection ID.

Agencies managing many merchants should use child workspaces instead — one workspace per merchant with the agency invited as a member. That keeps credentials, billing, and audit trails cleanly separated.

• "Shopify rejected the client-credentials token exchange"— first confirm the values came from the Dev Dashboard app's Settings → Credentials panel, not the App automation token. If the app was created by a partner or agency organization and installed on a client-owned production store, use Shopify OAuth instead or create the app inside the store-owning Shopify organization.
• shop_not_permitted — the Dev Dashboard app and store are probably in different Shopify organizations. Confirm both appear under the same organization in dev.shopify.com.
• "The access token is valid but missing scopes" — you granted fewer scopes than ShopMCP needs. Re-check the list in step 2, release a new app version, approve the scope update on the store, then refresh the connected store row in ShopMCP.
• "Contains invalid scopes" in Shopify's Dev Dashboard — paste the scope list as comma-separated text, remove read_product_listings, write_companies, read_images, and any ShopMCP tool names such as shopify_list_files. Use read_files / write_files for Shopify Files access, and keep read_publications / write_publications out of the version until Shopify has enabled publication access for the app.
• shopifyqlQuery access denied — approve read_reports and Shopify protected customer data Level 2 access, then refresh or reconnect the store.
• Public-app install suddenly gets 401s after a long gap — the expiring offline refresh token may have aged out. Re-open ShopMCP from Shopify admin to re-trigger the install/auth flow and issue a fresh refresh token.
• 404 on connect — you're probably pointing at a vanity / custom domain. Use the *.myshopify.com subdomain instead.
• "Tool not available" on a write tool — check both gates: the Dev Dashboard app version needs the matching write_* scope, AND the Write tools toggle on Settings → Integrations → Shopify has to be on.