Shopify MCP

Overview Schema Source Related Servers Discussions Admin

shopify_graphql_query

Read-only

Run read-only GraphQL queries against a Shopify store's Admin API to retrieve products, orders, customers, inventory, and other data without mutation risk.

Instructions

Execute a read-only GraphQL query against a Shopify store's Admin API.

Universal entry point for reading any data the token's scopes permit: products, variants, orders, customers, inventory, fulfillments, discounts, locations, markets, metafields, metaobjects, segments, shop settings, etc.

Full GraphQL reference: https://shopify.dev/docs/api/admin-graphql

Write mutations are rejected by design. The query string is parsed and validated as read-only before transmission.

Idiomatic patterns:

Pagination: first: <=250, after: <cursor>, read pageInfo { hasNextPage endCursor }.
Search: pass a Shopify search string to the query: arg on connections, e.g. orders(first: 100, query: "created_at:>=2026-04-01 financial_status:paid").
Money: totalPriceSet { shopMoney { amount currencyCode } }.
For datasets >10k records, use shopify_bulk_query instead.

Args: query: GraphQL document. Must be a query or a fragment. Subscription and mutation operations are rejected - with one narrow exception, bulkOperationCancel. For bulk exports, use shopify_bulk_query. variables: Optional variables dict passed as GraphQL variables. shop: Store alias (from shopify_list_stores) or domain. Required when multiple stores are configured; optional (auto-selected) when there's only one store. api_version: Override API version (default "2026-04"). Format "YYYY-MM".

Input Schema

TableJSON Schema

Name	Required	Description	Default
`shop`	No
`query`	Yes
`variables`	No
`api_version`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.1.0Sep 10, 2026

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnlyHint annotation, the description adds real behavioral detail: 'The query string is parsed and validated as read-only before transmission,' and mutation/subscription operations are rejected except for the narrow `bulkOperationCancel` exception. This meaningfully expands on what the annotations already declare without contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with purpose and structured into idiomatic patterns and per-argument details. It is somewhat long and repeats the bulk-query alternative twice, but the length earns its place because most content is call-critical rather than decorative.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description does not need to explain returns. It covers the required query format, variables, shop selection, api versioning, pagination patterns, search usage, and the bulk export boundary. No essential call context appears missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description compensates by explaining each parameter: the GraphQL document shape and restrictions, the `variables` dict, the `shop` alias/domain requirements, and `api_version` default plus 'YYYY-MM' format. This turns a bare schema into usable guidance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Execute a read-only GraphQL query against a Shopify store's Admin API,' naming a specific verb, resource, and constraint. It then clarifies this is the 'Universal entry point for reading any data the token's scopes permit' and lists resource types, which distinguishes it from mutation and bulk siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It clearly says to use the tool for reading any data the token permits and explicitly warns that write mutations are rejected. It also provides an alternative: 'For datasets >10k records, use shopify_bulk_query instead,' so an agent knows when to switch tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server