Shopify Admin MCP

Shopify Admin MCP

English | Русский

A1 Shopify Admin MCP 通过 Admin GraphQL API 将 AI 应用连接到一个 Shopify 商店。你可以用自然语言询问产品、订单、客户、库存、折扣和商店数据；助手会使用服务端预置的工具并显示结果。

• 每个服务端对应一个商店。 商店域名和凭据来自配置；工具无法切换到其他商店。
• 令牌始终有效。 向服务端提供 Shopify Dev Dashboard 应用的客户端 ID 和密钥，它会自行生成 Admin API 令牌，仅将其保存在内存中，并在 24 小时过期前重新生成。旧版自定义应用生成的现成令牌也可使用。
• 16 个专用工具。 读取商店数据、产品、订单、客户、地点、库存和折扣，并创建或更新受支持的记录。
• 清晰呈现 GraphQL 错误。 Shopify 的失败变更操作也可能返回 HTTP 200，因此服务端会检查 userErrors，并拒绝空白或格式错误的 GraphQL 响应。
• 考虑成本的响应。 每个结果都会包含 GraphQL 成本桶：请求成本以及后续调用当前可用的点数。
• 风险一目了然。 读取操作为只读；产品、价格、库存和折扣写入操作会明确标示；取消订单和任意 GraphQL 操作会标示为破坏性操作。

从只读请求开始：

显示最新订单和当前有库存的产品。

连接服务端 · 探索使用场景 · 查看技术文档

一分钟了解使用方式

你： 显示最新订单和当前有库存的产品。

助手： 显示近期订单及其状态和总额，然后显示产品、价格和库存。不会进行任何更改。

你： 准备一个名为 SUMMER、有效期为两周的 20% 折扣码。

助手： 显示拟创建的折扣码、折扣比例、日期和限制，然后在创建前请求确认。

你： 确认。

目录

• 快速开始
• 可以让它做什么
• 哪些内容会在 Shopify 中更改
• 获取访问权限
• 配置
• 数据、限制和后台工作
• 技术文档
• 支持

快速开始

你需要 Node.js 20+、一个商店域名（例如 my-store.myshopify.com）和 Admin API 凭据。推荐使用 Shopify Dev Dashboard 应用的客户端 ID 和密钥：服务会自行用它们换取访问令牌，并保持令牌有效。由于 Shopify 为此授权方式签发的令牌会在 24 小时后过期，因此这很重要。应用和商店必须属于同一个 Shopify 组织。

1. 获取访问权限，并准备好应用的客户端 ID 和客户端密钥。
2. 将 MCP 服务添加到你的 AI 应用。
3. 发送开篇部分中的安全请求。

该服务通过 npx 在本地使用 stdio 运行。仅在浏览器中使用的 ChatGPT 和 Claude 网页会话无法直接启动本地 stdio 进程。

以下所有代码片段都使用这对凭据。如果你的商店仍保留着由管理员创建的自定义应用所生成的现成令牌，请将 SHOPIFY_CLIENT_ID 和 SHOPIFY_CLIENT_SECRET 替换为单个 SHOPIFY_ACCESS_TOKEN——参见获取访问权限。

codex mcp add shopify-admin \
  --env SHOPIFY_STORE_DOMAIN=my-store.myshopify.com \
  --env SHOPIFY_CLIENT_ID=your_client_id \
  --env SHOPIFY_CLIENT_SECRET=your_client_secret \
  -- npx -y mcp-shopify-admin@latest

codex mcp list

claude mcp add \
  --env SHOPIFY_STORE_DOMAIN=my-store.myshopify.com \
  --env SHOPIFY_CLIENT_ID=your_client_id \
  --env SHOPIFY_CLIENT_SECRET=your_client_secret \
  --transport stdio --scope user shopify-admin \
  -- npx -y mcp-shopify-admin@latest

claude mcp list

{
  "mcpServers": {
    "shopify-admin": {
      "command": "npx",
      "args": ["-y", "mcp-shopify-admin@latest"],
      "env": {
        "SHOPIFY_STORE_DOMAIN": "my-store.myshopify.com",
        "SHOPIFY_CLIENT_ID": "your_client_id",
        "SHOPIFY_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

{
  "mcpServers": {
    "shopify-admin": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-shopify-admin@latest"],
      "env": {
        "SHOPIFY_STORE_DOMAIN": "my-store.myshopify.com",
        "SHOPIFY_CLIENT_ID": "your_client_id",
        "SHOPIFY_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

{
  "inputs": [
    {
      "type": "promptString",
      "id": "shopify_store_domain",
      "description": "Shopify store domain, for example my-store.myshopify.com"
    },
    {
      "type": "promptString",
      "id": "shopify_client_id",
      "description": "Client ID of the Shopify Dev Dashboard app"
    },
    {
      "type": "promptString",
      "id": "shopify_client_secret",
      "description": "Client secret of that app",
      "password": true
    }
  ],
  "servers": {
    "shopify-admin": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-shopify-admin@latest"],
      "env": {
        "SHOPIFY_STORE_DOMAIN": "${input:shopify_store_domain}",
        "SHOPIFY_CLIENT_ID": "${input:shopify_client_id}",
        "SHOPIFY_CLIENT_SECRET": "${input:shopify_client_secret}"
      }
    }
  }
}

你可以让它做什么

• 检查商店。 显示商店详情、地点、产品、订单、客户或折扣。
• 处理产品。 创建产品草稿、更新产品字段或更改变体价格。
• 跟踪库存。 查找地点，并为库存项目设置可用数量的绝对值。
• 查看订单。 搜索订单、检查完整订单，或在明确选择退款和补货方式后取消符合条件的订单。
• 管理折扣。 列出已有折扣，或创建基本的折扣码。
• 使用备用入口。 执行任意 Admin GraphQL 文档，以实现没有专用工具支持的功能。

Shopify 中可以更改的内容

此服务不提供用于创建订单、履行订单、写入客户数据、创建款式、管理媒体、创建定向折扣或将产品发布到销售渠道的专用工具。只有在理解文档及其 userErrors 响应后，才使用 graphql_request。

AI 客户端可能会在写入前请求确认，但确认行为由该客户端决定。明确要求创建、更新、设置或取消，即授权执行相应的服务操作。

获取访问权限

服务通过以下两种方式之一进行身份验证：使用 Dev Dashboard 应用的客户端 ID 和密钥，由服务自行兑换访问令牌；或者使用现成的 Admin API 访问令牌，并原样发送该令牌。如果两者都已配置，则优先使用现成的令牌。

Dev Dashboard 应用（推荐）

Shopify 已从 2026-01-01 起停止允许新建通过管理后台创建的自定义应用，因此，如今设置任何商店都应采用此方式。

1. 在 Shopify Dev Dashboard 中或使用 Shopify CLI 创建应用，并确保应用与商店属于同一个 Shopify 组织。
2. 为应用授予所需的 Admin API 访问范围，例如 read_products、write_products、read_orders、read_customers、read_locations、write_inventory、read_discounts 和 write_discounts。
3. 在商店中安装应用。
4. 将应用的客户端 ID 和客户端密钥分别用作 SHOPIFY_CLIENT_ID 和 SHOPIFY_CLIENT_SECRET。

之后，服务会自行通过 客户端凭据授权，向 https://{store}.myshopify.com/admin/oauth/access_token 发起请求。Shopify 返回的令牌有效期为 24 小时；服务仅在内存中保存令牌，绝不写入磁盘；在令牌过期前不久自动重新获取；允许并行工具调用共用一次令牌交换；若 API 返回 401，则获取新令牌。无需手动续期。

此授权方式仅在应用和商店属于同一个 Shopify 组织时有效。否则，Shopify 会返回 shop_not_permitted，服务会转达提示，指出组织不匹配。重新签发凭据并无帮助：请将应用移入商店所属的组织，或改用该组织中的商店。

现有的由管理员创建的自定义应用（旧版）

在 2026-01-01 之前于 Shopify 管理后台创建的应用仍可正常运行，其令牌也仍然有效。如果你已经在维护此类应用：

1. 在 Shopify 管理后台打开该应用。
2. 确认所需的 Admin API 访问范围，例如 read_products、write_products、read_orders、read_customers、read_locations、write_inventory、read_discounts 和 write_discounts。
3. 如果 Shopify 要求你生成凭据，请安装或重新安装该应用。
4. 将签发的 Admin API 访问令牌用作 SHOPIFY_ACCESS_TOKEN。

服务会原样发送此令牌，且不会刷新它，因此令牌失效后需要由你自行更换。请参阅 Shopify 的旧版管理员创建的自定义应用文档。

请将访问令牌和客户端密钥视为密码，切勿将其提交到 Git。为安全起见，请使用 Shopify 开发商店进行测试。

配置

* 本地测试时，SHOPIFY_API_BASE 可以替代商店域名，但实际 Shopify 请求仍需要凭据。

** 必须使用以下两种身份验证方式之一：SHOPIFY_CLIENT_ID + SHOPIFY_CLIENT_SECRET，或 SHOPIFY_ACCESS_TOKEN。如果两者都未设置，服务仍会启动并响应 initialize，但每次工具调用都会返回错误，说明这两种方式。变量在启动时读取，因此更改后请重启服务。

数据、限制和后台工作

• GraphQL 成本桶。 Shopify 提供时，每个结果都会包含 actualQueryCost、currentlyAvailable、maximumAvailable 和 restoreRate。通常，使用 first 参数且值不超过 250 的页面，比多个小页面更节省成本。
• 重试策略不对称。 THROTTLED 和 HTTP 429 错误会根据 Shopify 报告的等待时间重试。5xx 和网络错误仅对读取请求重试；发生此类故障后不会重放变更操作。
• 订单历史记录。 超过 60 天的订单需要 read_all_orders 范围；没有该范围时，Shopify 不会返回这些订单。
• 无后台监控。 服务仅在收到调用时运行。如果你的 AI 应用支持计划任务，可以定期检查订单或库存。
• 匿名遥测。 服务会发送技术性安装和工具使用事件，但不包含密钥、商店数据、参数或提示词。设置 ASKADS_TELEMETRY=0 可为所有 Ask Ads MCP 服务禁用遥测。

技术文档

• 功能目录 — 为 16 个工具中的每个工具提供一个以任务为导向的页面。
• 所有工具和参数
• 开发指南
• 发布指南
• Shopify Admin GraphQL API

支持

发现了错误或缺少某种使用场景？创建问题，或通过 Telegram 联系我们。

你已读到最后！