Shopify MCP Server

什么是 Shopify MCP Server？

Shopify MCP Server（GeLi2001 开发的 shopify-mcp）是一个社区版 Shopify MCP 服务器，通过 Shopify GraphQL Admin API 把 Claude、Cursor 等 MCP 客户端连接到你的店铺。它提供 31 个工具，覆盖商品、客户、订单、草稿订单、元字段（metafields）、库存和标签。

它通过 npx 在本地运行，直接调用店铺的 Admin API（默认版本 2026-01），因此可以作为面向店铺运营者和开发者的 Shopify Admin MCP 使用。它采用 MIT 许可证开源，并非 Shopify 官方开发。

如何使用 Shopify MCP Server？

前置条件：Node.js 18 或更高版本，以及一个可以安装自定义应用的 Shopify 店铺。

获取凭据。自 2026 年 1 月 1 日起，新的 Shopify 应用在 Dev Dashboard 中创建，并使用客户端凭据（client credentials）：

1. 在 Shopify 后台进入 Settings → Apps and sales channels。
2. 点击 Develop apps → Build app in dev dashboard。
3. 创建应用并配置 Admin API 权限范围：read_products、write_products、read_customers、write_customers、read_orders、write_orders。
4. 将应用安装到店铺，并复制 Client ID 和 Client Secret。

服务器会用它们换取访问令牌，并在过期前自动刷新（令牌有效期约 24 小时）。如果你有使用静态 shpat_ 令牌的旧版自定义应用，也可以改用 --accessToken。

Claude Desktop

将以下内容添加到 claude_desktop_config.json（macOS 位于 ~/Library/Application Support/Claude/，Windows 位于 %APPDATA%/Claude/）：

{
  "mcpServers": {
    "shopify": {
      "command": "npx",
      "args": [
        "shopify-mcp",
        "--clientId",
        "<YOUR_CLIENT_ID>",
        "--clientSecret",
        "<YOUR_CLIENT_SECRET>",
        "--domain",
        "<YOUR_SHOP>.myshopify.com"
      ]
    }
  }
}

如果使用旧版令牌，把 --clientId/--clientSecret 这一组参数替换为 "--accessToken", "<YOUR_ACCESS_TOKEN>"。

Claude Code

claude mcp add shopify -- npx shopify-mcp \
  --clientId YOUR_CLIENT_ID \
  --clientSecret YOUR_CLIENT_SECRET \
  --domain your-store.myshopify.com

Cursor 及其他客户端

任何能启动 stdio MCP 服务器的客户端，都可以在其 MCP 配置中使用上面相同的 npx shopify-mcp 命令和参数。

环境变量

除了命令行参数，你也可以把凭据写入 .env 文件，然后运行 npx shopify-mcp：

SHOPIFY_CLIENT_ID=your_client_id
SHOPIFY_CLIENT_SECRET=your_client_secret
MYSHOPIFY_DOMAIN=your-store.myshopify.com

旧版应用用 SHOPIFY_ACCESS_TOKEN 代替 Client ID 和 Secret。使用 --apiVersion 或 SHOPIFY_API_VERSION 可以指定其他 Admin API 版本。

Shopify MCP Server 的主要功能

• 31 个工具，覆盖商品、变体和选项、客户、订单、草稿订单、元字段、库存和标签
• 直接集成 Shopify GraphQL Admin API（默认 2026-01，可配置）
• 支持 Dev Dashboard 应用的客户端凭据认证并自动刷新令牌，同时兼容旧版 shpat_ 令牌
• 所有列表工具都支持游标分页（after/before）、sortKey 和 reverse
• 直接透传 Shopify 搜索语法，例如 financial_status:paid fulfillment_status:shipped tag:rush
• 智能订单查找：支持订单名（#77235）、数字 ID 或完整 GID
• 针对 API 和认证问题提供清晰的错误信息

Shopify MCP Server 工具

• 商品（8 个）：get-products、get-product-by-id、create-product、update-product 和 delete-product，以及用于尺码、颜色、价格、SKU 和条码的 manage-product-options、manage-product-variants 和 delete-product-variants。update-product 还可以处理 SEO 字段和商品系列归属。
• 客户：get-customers、get-customer-by-id、create-customer、update-customer（包括邮件营销授权）、delete-customer、用于合并重复客户的 customer-merge，以及 manage-customer-address。
• 订单：get-orders、get-order-by-id、get-customer-orders 和 update-order 用于读取和编辑。order-cancel、order-close-open、order-mark-as-paid、create-fulfillment（可附带物流跟踪）和 refund-create 会改变订单状态。
• 草稿订单：create-draft-order 用于电话、聊天或批发销售，complete-draft-order 将草稿转为正式订单。
• 元字段、库存和标签：get-metafields、set-metafields（一次最多 25 个）和 delete-metafields 适用于任何资源。inventory-set-quantities 设置某个地点的绝对库存数量，manage-tags 为任何可加标签的资源添加或移除标签。

Shopify MCP Server 的使用场景

• 订单运营：“本周哪些订单已付款但还未发货？给它们打上 rush 标签。”
• 商品目录：“为新款卫衣创建一个草稿商品，尺码 S–XL，售价 $49，并写一段 SEO 描述。”
• 客户服务：“查找订单 #77235，退款第二个商品行项目并重新入库。”
• 数据清理：“找出邮箱相同的客户并合并重复记录。”
• 库存：“根据今天的盘点，把主仓库中 SKU PROD-001 的可用数量设为 120。”
• 批发：为 B2B 买家创建带折扣的草稿订单，收到付款后再完成订单。

Shopify MCP Server 与替代方案对比

• Shopify Dev MCP（官方）：Shopify 官方的 Dev MCP 服务器（@shopify/dev-mcp）在本地运行，把 AI 工具连接到 Shopify 的开发者资源：文档、API schema 和代码帮助。它无需认证，也不是用来管理店铺商品和订单的工具。开发应用时用它；运营店铺时用这个 Shopify MCP 服务器。
• 其他社区版 Shopify MCP 服务器：有好几个名称相近的项目。注意 shopify-mcp-server 是另一个 npm 包，本项目的包名和命令都是 shopify-mcp。
• 直接调用 Admin API：对于定时任务或后端作业，直接用脚本调用 GraphQL Admin API 通常更简单。MCP 服务器最适合交互式、以对话驱动的工作。

Shopify MCP Server 常见问题排查

• 提示“SHOPIFY_ACCESS_TOKEN environment variable is required”：你很可能运行了错误的包。请使用 npx shopify-mcp，而不是 shopify-mcp-server。
• 新应用认证失败：2026 年 1 月 1 日之后创建的应用使用 Dev Dashboard 的 Client ID 和 Client Secret，而不是静态令牌。请确认应用已安装到你在 --domain 中指定的店铺。
• 调用工具时被拒绝访问：应用缺少权限范围。为商品、客户或订单添加对应的 read_/write_ 权限并重新安装应用。
• 创建的商品只有一个 $0 的变体：带 productOptions 调用 create-product 时只会创建一个默认变体。之后用 manage-product-variants 并设置 strategy: REMOVE_STANDALONE_VARIANT 来创建带价格的真实变体。
• 查看日志：对于 Claude Desktop，运行 tail -n 20 -f ~/Library/Logs/Claude/mcp*.log。