shopify-dev-mcp

Shopify Dev MCP

Routes MCP tool calls for Shopify surfaces. Standard lookups, not deep reasoning.

⚠️ Skip if a bundled skill applies

The 7 official Shopify skills ship local validators (scripts/search_docs.mjs, scripts/validate.mjs) that are faster than the MCP and don't require a server round-trip:

Surface	Use this skill instead
Admin GraphQL	shopify-admin
App Home <s-*> markup	shopify-polaris-app-home
Admin Action/Block extensions	shopify-polaris-admin-extensions
Modern checkout <s-*> markup	shopify-polaris-checkout-extensions
Customer Account UI	shopify-polaris-customer-account-extensions
App Store pre-submission review	shopify-app-store-review
shopify.app.toml / CLI workflows	shopify-use-shopify-cli

Use shopify-dev-mcp ONLY when:

• The surface isn't in the table above (storefront-graphql, customer, partner, payments-apps, functions, hydrogen, liquid, custom-data).
• You're cross-referencing schemas across two surfaces in one conversation.
• The bundled script for an installed skill is unavailable or erroring.

⚠️ NOT for legacy post-purchase

The MCP does NOT index @shopify/post-purchase-ui-extensions-react. validate_component_codeblocks rejects every legacy post-purchase component by design — the validator's polaris-checkout-extensions enum value covers MODERN @shopify/ui-extensions <s-*> web components only.

For the legacy SDK: use the post-purchase-ui-extension skill and validate with tsc --noEmit.

Instructions

1 — Initialize

Call learn_shopify_api with the target api surface. Consult the API Surfaces appendix below to confirm the correct api value. Extract the returned conversationId — pass it to every subsequent call.

2 — Route

Determine which tool answers the question: doc search, schema introspection, extension targets, or full page fetch. Consult the Tools Reference below for parameters and gotchas.

3 — Use

Call the appropriate tool(s). If switching API surfaces mid-conversation, call learn_shopify_api again with the existing conversationId and the new api.

4 — Validate

Before committing any generated code:

• <s-*> component markup → validate_component_codeblocks (mandatory)
• GraphQL queries/mutations → validate_graphql_codeblocks (mandatory)
• Liquid/theme files → validate_theme (mandatory)

5 — Fix and re-validate

If validation fails, fix errors and re-validate. Increment revision on the same artifactId to track iterations. If validation fails twice on the same artifact, stop and surface the error to the user.

---

API Surfaces

All 15 valid values for the api param on learn_shopify_api:

api value	Description
admin	Admin GraphQL API (orders, products, metafields)
admin-execution	Admin API execution surface (Shopify-internal — present in the learn_shopify_api enum but NOT in the GraphQL validator enum)
storefront-graphql	Storefront API (custom storefronts, cart ops)
partner	Partner API (dashboard data, apps, referrals)
customer	Customer Account API (orders, payment methods, addresses)
payments-apps	Payments Apps API (payment provider integrations)
functions	Shopify Functions (discounts, delivery, cart transforms)
polaris-app-home	App Home UI (<s-*> web components in admin iframe)
polaris-admin-extensions	Admin action/block extensions
polaris-checkout-extensions	Modern checkout web-component extensions (@shopify/ui-extensions, <s-*>). Does NOT cover @shopify/post-purchase-ui-extensions-react.
polaris-customer-account-extensions	Customer account page extensions
pos-ui	Point of sale UI extensions
hydrogen	Hydrogen framework
liquid	Liquid templates
custom-data	Metafields and metaobjects

Note: validate_component_codeblocks accepts one additional value — storefront-web-components — that is NOT valid for learn_shopify_api. See the validator's section below.

Tools Reference

Tool availability varies by MCP server build. Some installations register only a subset (typically: learn_shopify_api, search_docs_chunks, validate_component_codeblocks, validate_graphql_codeblocks, validate_theme). If a tool below is not callable in your environment, fall back to search_docs_chunks.

learn_shopify_api

Purpose: Load API overview and get a conversationId. Must be called before all other tools.

Param	Type	Required	Notes
api	enum (15 values above)	Yes	Target surface
model	string	No (always provide)	Telemetry. Schema marks not-required, but the description says "ALWAYS provide". Pass the current model name; pass 'none' if unknown.
conversationId	string (UUID)	No	Pass existing ID when switching surfaces mid-conversation. Omit on first call — a new ID is generated and returned.

Returns: conversationId (UUID) — required by every subsequent tool call.

Gotchas:

• Call again (with same conversationId) when switching API surfaces. This loads new context without losing conversation state.
• The response includes a component/API index for the surface — use it to guide subsequent search_docs_chunks queries.

---

search_docs_chunks

Purpose: Semantic search over shopify.dev documentation. Returns relevant doc chunks with URLs.

Param	Type	Required	Notes
conversationId	string	Yes	From learn_shopify_api
prompt	string	Yes	Natural language search query
api_name	string	No	Filter results to a specific API surface (use the same value as api in learn_shopify_api)
max_num_results	number	No	Limit result count. Omit on first call; use when trimming for context-window constraints.

Gotchas:

• Prefer this over fetch_full_docs for targeted lookups.
• For storefront-graphql, this is the only reliable doc tool — introspect_graphql_schema and fetch_full_docs are restricted.

---

fetch_full_docs

Purpose: Fetch complete documentation pages by path. Use when you need full property/slot/event details from a page found via search_docs_chunks.

Param	Type	Required	Notes
conversationId	string	Yes	From learn_shopify_api
paths	string[]	Yes	Doc paths relative to site root, e.g. ["/docs/api/app-home"]

Gotchas:

• The learn_shopify_api response labels fetch_full_docs as DEPRECATED for some surfaces, but where present the tool still works. Prefer search_docs_chunks; fall back to fetch_full_docs for complete property/slot/event docs.
• For storefront-graphql, this tool is restricted — use search_docs_chunks instead.
• May not be registered in all MCP server builds.

---

validate_component_codeblocks

Purpose: Validate <s-*> web component markup against Shopify's schema. Catches hallucinated components, props, and prop values.

Param	Type	Required	Notes
conversationId	string	Yes	From learn_shopify_api
api	enum	Yes	One of: polaris-app-home, polaris-admin-extensions, polaris-checkout-extensions, polaris-customer-account-extensions, pos-ui, hydrogen, storefront-web-components (7 values)
code	array of { content: string, artifactId?: string, revision?: number }	Yes	Code blocks. content is required per item. Param key is code (not codeblocks).
extensionTarget	string	No*	Required for extension surfaces: polaris-admin-extensions, polaris-checkout-extensions, polaris-customer-account-extensions, pos-ui. Determines which components/APIs are available. Where learn_extension_target_types is registered, use it to discover valid targets.

Input format: Wrap code in a function — JS logic outside return, components inside return:

const Example = () => {
  const [value, setValue] = useState('');

  return (
    <s-page heading="Example">
      <s-section>
        <s-text-field label="Name" value={value} />
      </s-section>
    </s-page>
  );
};

Raw HTML also works, but the function wrapper is recommended.

Gotchas:

• The param is code (array), not codeblocks — opposite naming from validate_graphql_codeblocks.
• Mandatory after generating ANY <s-*> markup — never skip, even for small snippets.
• For polaris-checkout-extensions, pass the specific extensionTarget (e.g. purchase.checkout.block.render) to get accurate validation.
• The validator does not type App Bridge web components (<s-app-window>, <s-app-nav>) as JSX intrinsic elements — they will fail validation in TSX even though they're real components. Use raw HTML, the App Bridge React wrappers (<TitleBar>, <NavMenu>), or a JSX type augmentation.

---

GraphQL API enum

IMPORTANT — this enum differs from learn_shopify_api.

validate_graphql_codeblocks and introspect_graphql_schema share an expanded 18-value enum where functions splits into 13 specific subtypes. admin-execution is NOT in this enum — even though it's valid for learn_shopify_api.

Value	Description
admin	Admin GraphQL API
storefront-graphql	Storefront API
partner	Partner API
customer	Customer Account API
payments-apps	Payments Apps API
functions_cart_checkout_validation	Cart and Checkout Validation Function inputs
functions_cart_transform	Cart Transform Function inputs
functions_delivery_customization	Delivery Customization Function inputs
functions_discount	Discount Function inputs
functions_discounts_allocator	Discounts Allocator Function inputs
functions_fulfillment_constraints	Fulfillment Constraints Function inputs
functions_local_pickup_delivery_option_generator	Local Pickup Delivery Option Generator inputs
functions_order_discounts	Order Discounts Function inputs
functions_order_routing_location_rule	Order Routing Location Rule inputs
functions_payment_customization	Payment Customization Function inputs
functions_pickup_point_delivery_option_generator	Pickup Point Delivery Option Generator inputs
functions_product_discounts	Product Discounts Function inputs
functions_shipping_discounts	Shipping Discounts Function inputs

---

validate_graphql_codeblocks

Purpose: Validate GraphQL queries/mutations against the Shopify schema. Catches hallucinated fields and operations.

Param	Type	Required	Notes
conversationId	string	Yes	From learn_shopify_api
codeblocks	array of { content: string, artifactId?: string, revision?: number }	Yes	Each content is raw GraphQL (no markdown backticks). Param key is codeblocks (not code).
api	enum	No	Defaults to admin. See GraphQL API enum.

Gotchas:

• The param is codeblocks (array), not code — opposite naming from validate_component_codeblocks.
• Content must be raw GraphQL, not wrapped in markdown code fences.
• For Functions, use the specific functions_* subtype from the GraphQL API enum, not functions.

---

introspect_graphql_schema

Purpose: Explore GraphQL schema — find fields, types, queries, mutations, and required scopes.

Param	Type	Required	Notes
conversationId	string	Yes	From learn_shopify_api
query	string	Yes	Simple search term (e.g. product, discountProduct, capture). One concept at a time.
api	enum	No	Defaults to admin. Same expanded enum as validate_graphql_codeblocks — see GraphQL API enum.
filter	string[]	No	Filter results: all (default), types, queries, mutations. Pass as array, e.g. ["queries", "mutations"].

Fallback strategy (confirmed accurate):

1. Start with the most specific term from the request.
2. If no results, try broader terms or individual words (e.g. captureSession → try capture).
3. For list operations, try all, list, or the plural object name.
4. For mutations, try the action verb: create, update, delete.

Gotchas:

• Uses the same expanded api enum as validate_graphql_codeblocks — functions splits into 13 subtypes.
• For storefront-graphql, this tool is restricted — use search_docs_chunks instead.
• May not be registered in all MCP server builds.

---

learn_extension_target_types

Purpose: Get type declarations for components and APIs available within a specific extension target.

Param	Type	Required	Notes
conversationId	string	Yes	From learn_shopify_api
api	enum	Yes	The surface
extension_target	string	Yes	The specific extension target (e.g. purchase.checkout.block.render)

Supported surfaces:

• polaris-admin-extensions
• polaris-checkout-extensions
• polaris-customer-account-extensions
• pos-ui

Not supported:

• polaris-app-home — not an extension surface.

May not be registered in all MCP server builds. When unavailable, look up valid extension targets via search_docs_chunks instead.

---

validate_theme

Purpose: Validate Liquid and theme files (JSON locales, config, templates, JS, CSS, SVG).

Param	Type	Required	Notes
conversationId	string	Yes	From learn_shopify_api
absoluteThemePath	string	Yes	Absolute path to theme directory
filesCreatedOrUpdated	array of { path: string, artifactId?: string, revision?: number }	Yes	path is relative to the theme root

Validation Reference

Required params per surface for validate_component_codeblocks

Surface	api	extensionTarget required?
polaris-app-home	polaris-app-home	No
polaris-admin-extensions	polaris-admin-extensions	Yes
polaris-checkout-extensions	polaris-checkout-extensions	Yes
polaris-customer-account-extensions	polaris-customer-account-extensions	Yes
pos-ui	pos-ui	Yes
hydrogen	hydrogen	No
storefront-web-components	storefront-web-components	No

Artifact tracking

Both validate_component_codeblocks and validate_graphql_codeblocks support iterative tracking:

• artifactId — Stable ID for the code artifact. Omit on first validation (the tool generates one). Reuse the returned ID on subsequent validations of the same artifact.
• revision — Starts at 1. Increment on each re-validation of the same artifactId. Tracks validation retries vs. new validations.