Shopify MCP

Shopify MCP

一个 MCP 服务，通过 6 个通用工具提供完整的 Shopify Admin GraphQL API 只读接口（版本 2026-04）。在查询解析器层强制只读：变更操作会在到达 Shopify 之前被拒绝，而不仅仅是提醒不要执行。本服务专为多店铺场景设计：一个服务实例可服务多个店铺。

由 Scalably 构建并维护。基于 Model Context Protocol 运行。许可证：MIT。

为什么要在解析器层强制只读？ 让 AI Agent 获得线上店铺的写入权限，可能导致商品被删除或变体价格出错。本服务通过 解析 每条查询，在查询离开进程之前拒绝变更操作来强制只读，而不是相信模型会按规行事，也不只是依赖 Shopify 侧的访问范围。这是生产环境中的 Agent 真正需要的安全边界。（了解更多相关模式）

安装

Claude Code：

claude mcp add shopify -e SHOPIFY_DOMAIN=my-store.myshopify.com -e SHOPIFY_ACCESS_TOKEN=shpat_... -- uvx scalably-shopify-mcp

Codex：

codex mcp add shopify --env SHOPIFY_DOMAIN=my-store.myshopify.com --env SHOPIFY_ACCESS_TOKEN=shpat_... -- uvx scalably-shopify-mcp

Claude Desktop：从最新的 GitHub release 下载 shopify-mcp.mcpb 并打开。

配置

单店铺（最简单）

• SHOPIFY_DOMAIN 或 SHOPIFY_SHOP_DOMAIN - <shop>.myshopify.com
• 认证方式 A：SHOPIFY_ACCESS_TOKEN（旧版 shpat_）
• 认证方式 B：SHOPIFY_CLIENT_ID + SHOPIFY_CLIENT_SECRET（Dev Dashboard 自定义应用，客户端凭据 OAuth，24 小时令牌自动刷新）

单店铺会以别名 default 注册；调用工具时可以省略 shop 参数。

多店铺（代理商设置）

将 SHOPIFY_STORES 设置为一个 JSON 对象，其中键为别名，值为店铺配置：

{
  "main":   {"domain": "my-store.myshopify.com",        "client_id": "...", "client_secret": "..."},
  "outlet": {"domain": "my-store-outlet.myshopify.com", "client_id": "...", "client_secret": "..."},
  "legacy": {"domain": "legacy-store.myshopify.com",    "access_token": "shpat_..."}
}

• 每个店铺都可以使用 client_id + client_secret（Dev Dashboard OAuth）或 access_token（旧版 shpat_）。
• 别名格式：[a-z0-9][a-z0-9_-]{0,63}，加载时会规范化为小写。
• 令牌缓存按店铺域名隔离；某个店铺遭遇限流不会影响其他店铺。

所需访问范围（只读）

最低可用配置：read_products read_orders read_customers。

建议的基准配置：read_products read_orders read_customers read_inventory read_locations read_fulfillments read_discounts read_content read_themes read_files read_markets read_metaobjects read_metaobject_definitions read_reports read_translations read_locales read_shipping。

如需访问超过 60 天的订单历史记录，请添加 read_all_orders。如果 Agent 需要客户个人身份信息（PII），请在 Dev Dashboard 的 Configuration 中启用 Protected customer data access。

工具（6 个）

工具	功能
shopify_list_stores	列出为此 Agent 配置的所有 Shopify 店铺。请先调用。
shopify_graphql_query	执行任意只读 GraphQL 查询。解析器会拒绝变更操作。
shopify_graphql_introspect	查询架构信息，可获取完整目录或单个类型。
shopify_bulk_query	启动异步批量导出（JSONL）。
shopify_bulk_poll	轮询批量操作状态并获取下载 URL。
shopify_shopifyql	ShopifyQL 分析（类似 SQL；需要 read_reports）。

除列表工具外，其他工具都接受可选的 shop 参数（别名或域名）。配置了多个店铺时必填；仅配置一个店铺时会自动选择。

覆盖范围

完整的 Admin GraphQL API 只读接口：通过 shopify_graphql_query，可访问令牌访问范围内的任何对象、字段或连接。大规模数据（超过 10k 条记录）应使用 shopify_bulk_query。分析功能通过 shopify_shopifyql 提供。

配置

变量	必填	用途
SHOPIFY_DOMAIN、SHOPIFY_SHOP_DOMAIN	其中一个，或设置 SHOPIFY_STORES	单店管理域名，<shop>.myshopify.com
SHOPIFY_ACCESS_TOKEN	见上文	旧版 shpat_ 访问令牌（单店认证路径 B）
SHOPIFY_CLIENT_ID、SHOPIFY_CLIENT_SECRET	见上文	Dev Dashboard 自定义应用凭据（单店认证路径 A）
SHOPIFY_STORES	否	将别名映射到店铺配置的 JSON 对象；优先级高于上述单店变量
SHOPIFY_STORE_<ALIAS>_DOMAIN、_CLIENT_ID、_CLIENT_SECRET、_ACCESS_TOKEN	否	SHOPIFY_STORES 的前缀键替代方案，适用于多店设置；每个店铺别名对应一组键
SHOPIFY_REQUEST_TIMEOUT_SECONDS	否	HTTP 请求超时时间，单位为秒（默认值 60）
SHOPIFY_LOG_LEVEL	否	INFO（默认值）或 DEBUG

只读强制校验

每个查询都会在发送前通过 graphql-core 解析。解析器会拒绝：

• subscription 操作（Admin API 本身也不支持）
• 除 bulkOperationCancel 以外的任何顶层 mutation（该操作会取消正在运行的批量任务，不会写入店铺数据）
• 格式错误的 GraphQL（语法错误）
• 超过 100KB 的查询

通用解析器允许列表中不包含 bulkOperationRunQuery。合法的批量导出会通过专用的 shopify_bulk_query 工具执行；该工具会使用相同的只读检查校验内部查询，然后再将其包装为批量 mutation。单一事实来源，不依赖 Shopify 端校验。

速率限制

按店铺独立使用基于成本的漏桶算法（Shopify 的模型）。每个响应都包含 extensions.cost.throttleStatus。发生 THROTTLED 错误时，服务会休眠 ceil((requestedQueryCost - currentlyAvailable) / restoreRate) 秒（至少 1 秒），最多重试 3 次，然后才返回错误。各店铺的漏桶彼此独立：一个店铺受到限流不会影响另一个店铺。

回复格式

工具回复与底层调用保持一致，而非采用统一封装。shopify_list_stores 返回 {alias, domain, name, currency, auth_mode} 的 JSON 数组；每个基于 GraphQL 的工具（shopify_graphql_query、shopify_graphql_introspect、shopify_bulk_query、shopify_bulk_poll、shopify_shopifyql）都会直接返回 Shopify Admin API 的原始响应 {"data": ..., "errors": ..., "extensions": ...}，不进行封装。工具级故障（输入错误、已隐藏的传输错误）会抛出普通错误。

限制

查询大小上限为 100KB。批量导出限制：每个查询恰好包含一个顶层连接，总连接数最多为 5，最大深度为 2，每个嵌套连接节点都必须选择 id 且不能使用别名；在 API 版本不晚于 2025-10 时，每个店铺一次只能运行一个批量操作；在 2026-01 及之后的版本中，最多可运行 5 个。API 版本默认为 2026-04；可通过每次调用的 api_version="YYYY-MM" 覆盖。

验证

每个版本都会在 CHANGELOG.md 中列出软件包版本、.mcpb 的 sha256，以及其所依据的生产提交。CI 会在每次推送时运行测试，并对构建好的 wheel 执行全新安装。

隐私政策

此连接器在您自己的设备上本地运行，使用您自己的 Shopify 凭据。它是 MCP 客户端与 Shopify Admin API 之间轻量级的只读桥接。

• 数据收集： 连接器不收集任何个人数据，也不包含遥测、分析或外部报告功能。它不会向外发送数据。
• 数据使用： 您查询的 Shopify 商店数据会返回到本地 MCP 客户端以完成您的请求，不会用于任何其他目的。
• 数据存储： 连接器不会持久存储任何内容。访问令牌仅在进程运行期间保存在内存中，绝不会写入磁盘。唯一的网络目标是 Shopify 自有的 API（*.myshopify.com），并通过域名允许列表强制限制。
• 第三方共享： 无。数据只会在您的设备与 Shopify 之间流动。任何第三方（包括连接器作者）都不会收到您的数据或凭据。
• 保留期限： 进程退出后，连接器不会保留任何数据。
• 机密信息处理： 访问令牌、客户端密钥以及所有 Shopify 令牌前缀都会在日志和错误消息中隐藏。
• 联系方式： [email protected]

此政策的规范托管版本：https://scalably.io/connector-privacy.html

许可证

MIT。版权所有：Scalably。

了解更多

我们在 scalably.io/blog 分享构建生产级 MCP 服务和 AI Agent 的经验：

• 如何使用 Python 构建 MCP 服务，介绍此处采用的只读强制执行模式，该模式来自我们在生产环境中运行的服务
• 什么是 MCP 服务？，介绍主机/客户端/服务端模型
• MCP Inspector：调试你的 MCP 服务，介绍需要留意的静默故障

参考资料

• Shopify Admin GraphQL API
• 客户端凭据授权
• 速率限制
• 批量操作
• ShopifyQL