Shopify

Shopify MCP 服务

适用于 Shopify API 的 MCP 服务，可通过 GraphQL API 与商店数据交互。此服务提供用于管理产品、客户、订单等的工具。

📦 软件包名称：@kisasa/shopify-mcp 🚀 命令：shopify-mcp（不是 shopify-mcp-server）

基于 lucasjahn/shopify-mcp 构建，而后者是 GeLi2001/shopify-mcp 的分支。请参阅致谢。

功能

• 产品管理：对产品、变体和选项进行完整的增删改查，包括变体图片和库存策略（8 个工具）
• 产品媒体：通过 URL 为产品添加图片，并检查处理状态（2 个工具）
• 销售渠道发布：列出销售渠道，并在这些渠道上发布或取消发布产品（4 个工具）
• 客户管理：完整的增删改查、合并和地址管理（8 个工具）
• 订单管理：智能查询、取消、关闭/重新打开、标记为已付款、履行、退款（10 个工具）
• 元字段管理：获取、设置和删除任意资源上的元字段（3 个工具）
• 集合管理：列出集合，并获取包含产品的集合详情（2 个工具）
• 配置与发现：商店信息、元字段定义、地点、市场（5 个工具）
• 库存与定价：设置数量、查看库存级别/商品、价格表、详细变体（5 个工具）
• 标签管理：为任意支持标签的资源添加/移除标签，包括批量操作（2 个工具）
• 增强型订单工具：交易、履行订单、退款详情（3 个工具）
• 字段选择：所有 GET 工具都支持 fields 参数，只获取所需数据
• 仅计数模式：列表工具支持 countOnly，无需获取数据即可获取结果数量
• 分页与排序：所有列表查询均支持基于游标的分页和排序键
• 高级筛选：所有列表端点均支持传递 Shopify 查询语法
• GraphQL 集成：直接集成 Shopify 的 GraphQL Admin API（2026-10）
• 全面的错误处理：清晰显示 API 和身份验证问题的错误消息

前置条件

1. Node.js（版本 18 或更高）
2. 拥有自定义应用的 Shopify 商店（请参阅下方的设置说明）

设置

身份验证

此服务支持两种身份验证方式：

选项 1：客户端凭据（2026 年 1 月起的 Dev Dashboard 应用）

自 2026 年 1 月 1 日起，新的 Shopify 应用将在 Dev Dashboard 中创建，并使用 OAuth 客户端凭据，而非静态访问令牌。

1. 在 Shopify 管理后台中，前往 Settings > Apps and sales channels

2. 点击 Develop apps > Build app in dev dashboard

3. 创建新应用并配置 Admin API scopes。核心权限范围包括：

   • read_products、write_products
   • read_customers、write_customers
   • read_orders、write_orders

   有些工具需要额外的权限范围。只添加你会用到的功能所需的权限：

   权限范围	用途
   read_all_orders	60 天以前的订单（否则订单工具只能看到近期订单）
   read_inventory、write_inventory	get-inventory-levels、inventory-set-quantities
   read_locations	get-locations、get-inventory-levels
   read_markets	get-markets
   read_draft_orders、write_draft_orders	create-draft-order、complete-draft-order
   read_merchant_managed_fulfillment_orders、write_merchant_managed_fulfillment_orders	get-fulfillment-orders、create-fulfillment
   read_publications、write_publications	get-publications、get-product-publications、publish-product、unpublish-product

   每个工具所需权限的完整列表如下：

   read_products,write_products,read_customers,write_customers,read_orders,write_orders,read_all_orders,read_inventory,write_inventory,read_locations,read_markets,read_draft_orders,write_draft_orders,read_merchant_managed_fulfillment_orders,write_merchant_managed_fulfillment_orders,read_publications,write_publications
   

   更改权限范围后，发布新版本的应用，在商店中批准该版本，然后重启 MCP 服务，使其获取具有新权限范围的令牌。

4. 在你的商店中安装该应用

5. 从应用的 API 凭据中复制 Client ID 和 Client Secret

服务器会自动将这些凭据换取访问令牌，并在令牌过期前刷新（令牌有效期约为 24 小时）。

选项 2：静态访问令牌（旧版应用）

如果你已有使用静态 shpat_ 访问令牌的自定义应用，仍可直接使用该令牌。

在 Claude Desktop 中使用

客户端凭据（推荐）：

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

通过环境变量使用客户端凭据（避免在命令行中暴露机密）：

{
  "mcpServers": {
    "shopify": {
      "command": "npx",
      "args": ["-y", "@kisasa/shopify-mcp"],
      "env": {
        "MYSHOPIFY_DOMAIN": "<YOUR_SHOP>.myshopify.com",
        "SHOPIFY_CLIENT_ID": "<YOUR_CLIENT_ID>",
        "SHOPIFY_CLIENT_SECRET": "<YOUR_CLIENT_SECRET>"
      }
    }
  }
}

要连接多个商店，请为每个商店添加一个条目，并使用不同的名称（例如 "shopify-store-a"、"shopify-store-b"）。

静态访问令牌（旧版）：

{
  "mcpServers": {
    "shopify": {
      "command": "npx",
      "args": [
        "@kisasa/shopify-mcp",
        "--accessToken",
        "<YOUR_ACCESS_TOKEN>",
        "--domain",
        "<YOUR_SHOP>.myshopify.com"
      ]
    }
  }
}

Claude Desktop 配置文件的位置：

• MacOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%/Claude/claude_desktop_config.json

在 Claude Code 中使用

客户端凭据：

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

静态访问令牌（旧版）：

claude mcp add shopify -- npx @kisasa/shopify-mcp \
  --accessToken YOUR_ACCESS_TOKEN \
  --domain your-store.myshopify.com

替代方案：使用环境变量在本地运行

如果你更愿意使用环境变量，而非命令行参数：

1. 创建一个 .env 文件，填写你的 Shopify 凭据：

   客户端凭据：

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

   静态访问令牌（旧版）：

   SHOPIFY_ACCESS_TOKEN=your_access_token
   MYSHOPIFY_DOMAIN=your-store.myshopify.com
   

2. 使用 npx 运行服务器：

   npx @kisasa/shopify-mcp
   

直接安装（可选）

如果你想全局安装该软件包：

npm install -g @kisasa/shopify-mcp

然后运行它：

shopify-mcp --clientId=<ID> --clientSecret=<SECRET> --domain=<YOUR_SHOP>.myshopify.com

其他选项

• --apiVersion：指定 Shopify API 版本（默认值：2026-10）。也可以通过 SHOPIFY_API_VERSION 环境变量设置。

⚠️ 重要： 如果使用命令行参数时看到有关“需要 SHOPIFY_ACCESS_TOKEN 环境变量”的错误，可能是安装了其他软件包。请确认使用的是 @kisasa/shopify-mcp，而不是 shopify-mcp-server 或未加作用域的 shopify-mcp。

可用工具（51）

共享功能

所有列表查询工具（get-products、get-customers、get-orders、get-customer-orders、get-collections）均支持：

• 基于游标的分页：after / before（游标字符串），响应中包含 pageInfo（hasNextPage、hasPreviousPage、startCursor、endCursor）
• 排序：sortKey（各资源专属的枚举值）和 reverse（布尔值）
• 高级筛选：query 或 searchQuery 参数，接受 Shopify 查询语法
• 字段选择：fields 参数，用于仅获取特定字段，减少响应大小
• 仅计数模式：countOnly 参数仅返回 { count: N }，不获取任何资源数据 — 可用于在分页前估算查询结果数量

产品管理（8 个工具）

1. get-products

   • 分页和排序获取所有产品，或按标题搜索
   • 输入：
     • searchTitle（字符串，可选）：按标题筛选产品（会包装为 title:*...*）
     • limit（数字，默认值：10）：要返回的产品数量上限
     • query（字符串，可选）：原始 Shopify 查询字符串（例如 "status:active vendor:Nike tag:sale"）
     • sortKey（字符串，可选）：以下之一：CREATED_AT、ID、INVENTORY_TOTAL、PRODUCT_TYPE、PUBLISHED_AT、RELEVANCE、TITLE、UPDATED_AT、VENDOR
     • reverse（布尔值，可选）：反转排序顺序
     • after / before（字符串，可选）：分页游标
     • fields（数组，可选）：要获取的字段。可用字段：id、title、description、handle、status、createdAt、updatedAt、totalInventory、vendor、productType、tags、mediaCount、priceRange、media、variants（前 10 个，包含 id、title、price、inventoryQuantity、sku、barcode、inventoryPolicy）
     • countOnly（布尔值，可选）：仅返回 { count: N }

2. get-product-by-id

   • 按 ID 获取指定产品的完整详情，包括 SEO、选项、媒体、变体和系列
   • 输入：
     • productId（字符串，必填）：Shopify 产品 GID
   • 返回：productType、descriptionHtml、seo、options（包含 optionValues）、media（图片）、variants、collections、tags、vendor、价格范围、库存

3. create-product

   • 创建新产品。使用 productOptions 时，Shopify 会注册所有选项值，但只创建一个默认变体（每个选项的第一个值，价格为 $0）。之后使用 manage-product-variants 和 strategy: REMOVE_STANDALONE_VARIANT 创建所有带价格的实际变体。
   • 输入：
     • title（字符串，必填）：产品标题
     • descriptionHtml（字符串，可选）：包含 HTML 的描述
     • handle（字符串，可选）：URL 别名。若省略，则根据标题自动生成
     • vendor（字符串，可选）：产品供应商
     • productType（字符串，可选）：产品类型
     • tags（字符串数组，可选）：产品标签
     • status（字符串，可选）："ACTIVE"、"DRAFT" 或 "ARCHIVED"。默认值为 "DRAFT"
     • seo（对象，可选）：用于搜索引擎的 { title, description }
     • metafields（对象数组，可选）：自定义元字段（namespace、key、value、type）
     • productOptions（对象数组，可选）：内联创建的选项，例如 [{ name: "Size", values: [{ name: "S" }, { name: "M" }] }]。最多 3 个选项。
     • collectionsToJoin（字符串数组，可选）：要将产品加入的系列 GID

4. update-product

   • 更新现有产品的字段
   • 输入：
     • id（字符串，必填）：Shopify 产品 GID
     • title（字符串，可选）：新标题
     • descriptionHtml（字符串，可选）：新描述
     • handle（字符串，可选）：新的 URL 别名
     • vendor（字符串，可选）：新供应商
     • productType（字符串，可选）：新产品类型
     • tags（字符串数组，可选）：新标签（覆盖现有标签）
     • status（字符串，可选）："ACTIVE"、"DRAFT" 或 "ARCHIVED"
     • seo（对象，可选）：供搜索引擎使用的 { title, description }
     • metafields（对象数组，可选）：要设置或更新的元字段
     • collectionsToJoin（字符串数组，可选）：要将产品添加到的系列 GID
     • collectionsToLeave（字符串数组，可选）：要将产品从中移除的系列 GID
     • redirectNewHandle（布尔值，可选）：若为 true，旧别名将重定向到新别名

5. delete-product

   • 删除产品
   • 输入：
     • id（字符串，必填）：Shopify 产品 GID

6. manage-product-options

   • 创建、更新或删除产品选项（例如尺寸、颜色）
   • 输入：
     • productId（字符串，必填）：Shopify 产品 GID
     • action（字符串，必填）："create"、"update" 或 "delete"
     • variantStrategy（字符串，可选）："LEAVE_AS_IS"（默认）或 "CREATE" — 控制添加选项时是否生成新的变体组合
     • 对于 action: "create"：
       • options（数组，必填）：要创建的选项，例如 [{ name: "Size", values: ["S", "M", "L"] }]
     • 对于 action: "update"：
       • optionId（字符串，必填）：要更新的选项 GID
       • name（字符串，可选）：选项的新名称
       • position（数字，可选）：新位置
       • valuesToAdd（字符串数组，可选）：要添加的值
       • valuesToDelete（字符串数组，可选）：要移除的值 GID
     • 对于 action: "delete"：
       • optionIds（字符串数组，必填）：要删除的选项 GID

7. manage-product-variants

   • 批量创建或更新产品变体
   • 输入：
     • productId（字符串，必填）：Shopify 产品 GID
     • strategy（字符串，可选）：创建时如何处理默认变体。"DEFAULT"（自动移除 "Default Title"）、"REMOVE_STANDALONE_VARIANT"（推荐，可获得完全控制权）或 "PRESERVE_STANDALONE_VARIANT"
     • variants（数组，必填）：要创建或更新的变体。每个变体包含：
       • id（字符串，可选）：用于更新的变体 GID。省略则创建新变体
       • price（字符串，可选）：价格，例如 "49.00"
       • compareAtPrice（字符串，可选）：用于显示折扣的划线价
       • sku（字符串，可选）：SKU（映射到 inventoryItem.sku）
       • tracked（布尔值，可选）：是否跟踪库存。按需打印产品设为 false
       • taxable（布尔值，可选）：该变体是否应纳税
       • barcode（字符串，可选）：条形码
       • weight（数字，可选）：变体重量
       • weightUnit（字符串，可选）："GRAMS"、"KILOGRAMS"、"OUNCES" 或 "POUNDS"
       • optionValues（数组，可选）：选项值，例如 [{ optionName: "Size", name: "A4" }]
       • mediaId（字符串，可选）：用作变体图片的产品媒体 GID（gid://shopify/MediaImage/...）。该媒体必须已附加到产品（参见 add-product-media），且状态应为 READY
       • inventoryPolicy（字符串，可选）："DENY" 会在库存为 0 时停止销售，"CONTINUE" 允许超卖
   • 返回：{ created, updated, userErrors }。每个变体都包含 inventoryPolicy、mediaId 和 imageUrl。userErrors 会随结果返回（标记为 operation: "create" 或 "update"），不会作为异常抛出，因此务必检查

8. delete-product-variants

   • 从产品中删除一个或多个变体
   • 输入：
     • productId（字符串，必填）：Shopify 产品 GID
     • variantIds（字符串数组，必填）：要删除的变体 GID

产品媒体（2 个工具）

1. add-product-media

   • 通过公开 URL 将图片添加到现有产品（使用 productUpdate 和 media；productCreateMedia 已弃用）
   • 输入：
     • productId（字符串，必填）：Shopify 产品 GID
     • media（数组，必填）：要添加的图片，每项格式为 { originalSource, alt? }。originalSource 必须是 Shopify 可下载的公开访问 URL
   • 返回：{ productId, media, userErrors }，其中每个新媒体项都包含 id、status、alt、imageUrl 和 mediaErrors
   • Shopify 会异步处理媒体。新项通常会先处于 UPLOADED 或 PROCESSING 状态，且 imageUrl: null；使用 get-product-media 确认其状态变为 READY

2. get-product-media

   • 列出产品的媒体及其处理状态
   • 输入：
     • productId（字符串，必填）：Shopify 产品 GID
   • 返回：每项的 id、status（UPLOADED / PROCESSING / READY / FAILED）、mediaContentType、alt、imageUrl 和 mediaErrors（说明 FAILED 状态的原因）

示例：为某个变体指定专属图片

1. 使用图片 URL 调用 add-product-media
2. 调用 get-product-media，直到新项状态变为 READY，然后复制其 id
3. 使用 { id: "<variant GID>", mediaId: "<media GID>" } 调用 manage-product-variants

销售渠道发布（4 个工具）

这些工具适用于销售渠道（带有应用目录的发布渠道，例如 Online Store 和 Point of Sale）。不包括市场和 B2B 目录。需要 read_publications 和 write_publications 权限范围。

1. get-publications

   • 列出商店的销售渠道
   • 输入：无
   • 返回：每个渠道的 id、name（例如 "Online Store"）、handle（例如 "online_store"）、autoPublish 和 supportsFuturePublishing

2. get-product-publications

   • 显示产品是否已发布到每个销售渠道
   • 输入：
     • productId（字符串，必填）：Shopify 产品 GID
   • 返回：{ productId, title, publications }，其中包含每个渠道的 publicationId、name、published 和 publishDate

3. publish-product

   • 将产品发布到一个或多个销售渠道（使用 publishablePublish）
   • 输入：
     • productId（字符串，必填）：Shopify 产品 GID
     • publicationIds（字符串数组，可选）：来自 get-publications 的发布 GID
     • publicationNames（字符串数组，可选）：与 get-publications 返回值完全一致的渠道名称，例如 ["Online Store", "Point of Sale"]
     • 必须且只能提供 publicationIds 或 publicationNames 其中之一。无法匹配任何渠道或匹配到多个渠道的名称会在任何更改发生前被拒绝
   • 返回：产品之后在每个渠道上的状态，以及 userErrors

4. unpublish-product

   • 将产品从一个或多个销售渠道取消发布（使用 publishableUnpublish）
   • 输入：与 publish-product 相同
   • 返回：产品之后在每个渠道上的状态，以及 userErrors

客户管理（8 个工具）

1. get-customers

   • 使用搜索、分页和排序列出客户
   • 输入：
     • searchQuery（string，可选）：自由文本或 Shopify 查询语法（例如 "country:US tag:vip orders_count:>5"）
     • limit（number，默认值：10）：要返回的客户数量上限
     • sortKey（string，可选）：以下选项之一：CREATED_AT、ID、LAST_UPDATE、LOCATION、NAME、ORDERS_COUNT、RELEVANCE、TOTAL_SPENT、UPDATED_AT
     • reverse（boolean，可选）：反转排序顺序
     • after / before（string，可选）：分页游标

2. get-customer-by-id

   • 根据 ID 获取单个客户的完整详细信息
   • 输入：
     • id（string，必填）：Shopify 客户 ID（仅限数字，例如 "6276879810626"）
   • 返回：姓名、电子邮件、电话、地址、标签、备注、税务状态、消费金额、订单数量、自定义元字段

3. create-customer

   • 创建新客户
   • 输入：
     • firstName（string，可选）：客户的名字
     • lastName（string，可选）：客户的姓氏
     • email（string，可选）：客户的电子邮件地址
     • phone（string，可选）：客户的电话号码
     • tags（字符串数组，可选）：要应用的标签
     • note（string，可选）：客户备注
     • taxExempt（boolean，可选）：客户是否免税
     • metafields（对象数组，可选）：自定义元字段（namespace、key、value、type）
     • addresses（对象数组，可选）：客户地址（address1、address2、city、provinceCode、zip、country、phone）

4. update-customer

   • 更新客户信息
   • 输入：
     • id（string，必填）：Shopify 客户 ID（仅限数字，例如 "6276879810626"）
     • firstName（string，可选）：客户的名字
     • lastName（string，可选）：客户的姓氏
     • email（string，可选）：客户的电子邮件地址
     • phone（string，可选）：客户的电话号码
     • tags（字符串数组，可选）：要应用于客户的标签
     • note（string，可选）：客户备注
     • taxExempt（boolean，可选）：客户是否免税
     • emailMarketingConsent（object，可选）：电子邮件营销许可设置
       • marketingState（string，必填）："NOT_SUBSCRIBED"、"SUBSCRIBED"、"UNSUBSCRIBED" 或 "PENDING"
       • consentUpdatedAt（string，可选）：ISO 8601 时间戳
       • marketingOptInLevel（string，可选）："SINGLE_OPT_IN"、"CONFIRMED_OPT_IN" 或 "UNKNOWN"
     • metafields（对象数组，可选）：客户元字段

5. delete-customer

   • 删除客户
   • 输入：
     • id（string，必填）：Shopify 客户 ID（仅限数字，例如 "6276879810626"）

6. customer-merge

   • 将两条客户记录合并为一条
   • 输入：
     • customerOneId（string，必填）：第一位客户的 GID
     • customerTwoId（string，必填）：第二位客户的 GID
     • overrideFields（object，可选）：指定从哪位客户保留哪些字段（firstName、lastName、email、phone、defaultAddress、note、tags）

7. manage-customer-address

   • 创建、更新或删除客户的邮寄地址
   • 输入：
     • customerId（string，必填）：客户 GID
     • action（string，必填）："create"、"update" 或 "delete"
     • addressId（string，可选）：地址 GID（更新或删除时必填）
     • address（object，可选）：地址字段（创建或更新时必填）：address1、address2、city、company、countryCode、firstName、lastName、phone、provinceCode、zip
     • setAsDefault（boolean，可选）：设为客户的默认地址

订单管理（10 个工具）

1. get-orders

   • 通过筛选、分页和排序获取订单
   • 输入：
     • status（字符串，可选）："any"、"open"、"closed" 或 "cancelled"。默认值为 "any"
     • limit（数字，默认值：10）：要返回的订单数上限
     • query（字符串，可选）：原始 Shopify 查询字符串（例如，"financial_status:paid fulfillment_status:shipped tag:rush"）
     • sortKey（字符串，可选）：CREATED_AT、ORDER_NUMBER、TOTAL_PRICE、FINANCIAL_STATUS、FULFILLMENT_STATUS、UPDATED_AT、CUSTOMER_NAME、PROCESSED_AT、ID、RELEVANCE 之一
     • reverse（布尔值，可选）：反转排序顺序
     • after / before（字符串，可选）：分页游标

2. get-order-by-id

   • 通过智能查找获取指定订单 — 支持订单名称（#77235 或 77235）、数字 ID（8054938337547）或完整 GID（gid://shopify/Order/...）
   • 输入：
     • orderId（字符串，必填）：订单名称、数字 ID 或完整 GID
   • 返回：价格、客户、收货／账单地址、商品项、标签、备注、元字段、取消原因、退货状态、折扣码、采购订单号、时间戳

3. update-order

   • 更新现有订单
   • 输入：
     • id（字符串，必填）：Shopify 订单 GID
     • tags（字符串数组，可选）：订单的新标签
     • email（字符串，可选）：更新订单中的客户电子邮箱
     • note（字符串，可选）：订单备注
     • phone（字符串，可选）：订单电话号码
     • poNumber（字符串，可选）：采购订单号
     • customAttributes（对象数组，可选）：自定义键值属性
     • metafields（对象数组，可选）：订单元字段
     • shippingAddress（对象，可选）：收货地址字段

4. get-customer-orders

   • 通过分页和排序获取指定客户的订单
   • 输入：
     • customerId（字符串，必填）：Shopify 客户 ID（仅限数字，例如，"6276879810626"）
     • limit（数字，默认值：10）：要返回的订单数上限
     • sortKey（字符串，可选）：与 get-orders 相同的排序键
     • reverse（布尔值，可选）：反转排序顺序
     • after / before（字符串，可选）：分页游标

5. order-cancel

   • 取消订单，可选择退款、重新入库和通知客户。不可撤销。
   • 输入：
     • orderId（字符串，必填）：订单 GID
     • reason（字符串，必填）："CUSTOMER"、"DECLINED"、"FRAUD"、"INVENTORY"、"OTHER" 或 "STAFF"
     • restock（布尔值，必填）：是否重新入库
     • notifyCustomer（布尔值，默认值：false）：通知客户
     • staffNote（字符串，可选）：内部备注
     • refund（布尔值，可选）：退款至原支付方式

6. order-close-open

   • 关闭或重新打开订单
   • 输入：
     • orderId（字符串，必填）：订单 GID
     • action（字符串，必填）："close" 或 "open"

7. order-mark-as-paid

   • 将订单标记为已付款（用于手动／线下付款）
   • 输入：
     • orderId（字符串，必填）：订单 GID

8. create-fulfillment

   • 创建履行记录（将商品标记为已发货），可选添加追踪信息
   • 输入：
     • lineItemsByFulfillmentOrder（数组，必填）：要履行的履行订单和商品项
     • trackingInfo（对象，可选）：追踪详情 { number, url, company }
     • notifyCustomer（布尔值，默认值：false）：发送发货通知

9. refund-create

   • 创建全额或部分退款，并可选择补货
   • 输入：
     • orderId（string，必填）：订单 GID
     • refundLineItems（array，可选）：要退款的商品行，包含 lineItemId、quantity、restockType（CANCEL/RETURN/NO_RESTOCK）、locationId
     • shipping（object，可选）：{ amount, fullRefund } 运费退款
     • note（string，可选）：退款备注
     • notify（boolean，可选）：发送退款通知

10. create-draft-order

    • 为电话/聊天销售、开具发票或批发创建草稿订单
    • 输入：
      • lineItems（array，必填）：商品变体（variantId）或自定义商品（title + 价格）。最多 499 个
      • customerId（string，可选）：客户 GID
      • email、phone、note、tags、poNumber（可选）
      • shippingAddress、billingAddress（object，可选）
      • appliedDiscount（object，可选）：{ title, value, valueType } 订单级折扣

草稿订单管理（1 个工具）

1. complete-draft-order

   • 完成草稿订单，将其转换为正式订单
   • 输入：
     • draftOrderId（string，必填）：草稿订单 GID
     • paymentGatewayId（string，可选）：支付网关 GID

Metafield 管理（3 个工具）

1. get-metafields

   • 获取任意 Shopify 资源（商品、订单、客户、变体、系列等）的 metafield
   • 输入：
     • ownerId（string，必填）：任意资源的 GID
     • namespace（string，可选）：按命名空间筛选
     • first（number，默认值：25）：要返回的 metafield 数量
     • after（string，可选）：分页游标

2. set-metafields

   • 为任意 Shopify 资源设置 metafield。以原子方式创建或更新最多 25 个 metafield
   • 输入：
     • metafields（array，必填）：要设置的 metafield，每个包含 ownerId、key、value，以及可选的 namespace、type

3. delete-metafields

   • 从任意 Shopify 资源中删除 metafield
   • 输入：
     • metafields（array，必填）：要删除的 metafield，每个包含 ownerId、namespace、key

库存管理（1 个工具）

1. inventory-set-quantities

   • 设置特定地点商品的绝对库存数量
   • 输入：
     • reason（string，必填）：变更原因（例如 "correction"、"cycle_count_available"）
     • name（string，必填）："available" 或 "on_hand"
     • quantities（array，必填）：商品项，包含 inventoryItemId、locationId、quantity，以及可选的 changeFromQuantity
       • changeFromQuantity（integer 或 null，可选）：你预期当前存储的数量。Shopify 仅在该数量仍匹配时应用变更，否则会返回 CHANGE_FROM_QUANTITY_STALE 错误。省略此项（或传入 null）即可在不进行此检查的情况下设置数量
     • idempotencyKey（string，可选）：请求的幂等键，Admin API 2026-04 及更高版本要求提供。如果省略，每次调用都会生成新的 UUID。仅在重试完全相同的请求时重复使用同一个键
   • 返回：{ idempotencyKey, adjustmentGroup, userErrors }。userErrors 包含 code（例如 CHANGE_FROM_QUANTITY_STALE、IDEMPOTENCY_KEY_PARAMETER_MISMATCH），错误会通过返回值提供而非抛出，因此务必检查这些错误

标签管理（2 个工具）

1. manage-tags

   • 为任何支持标签的资源（订单、产品、客户、草稿订单、文章）添加或移除标签
   • 输入：
     • id（字符串，必填）：资源的 GID（例如 gid://shopify/Product/123）
     • tags（字符串数组，必填）：要添加或移除的标签
     • action（字符串，必填）："add" 或 "remove"

2. manage-tags-bulk

   • 在单次调用中批量为最多 100 个资源添加或移除标签（并行运行变更操作）
   • 输入：
     • ids（字符串数组，必填）：资源 GID（最多 100 个）。数量更多时，请分多次调用
     • tags（字符串数组，必填）：要添加或移除的标签
     • action（字符串，必填）："add" 或 "remove"

集合管理（2 个工具）

1. get-collections

   • 搜索、分页并排序列集合
   • 输入：
     • query（字符串，可选）：Shopify 查询语法
     • limit（数字，默认值：10）：要返回的集合数量上限
     • sortKey、reverse、after/before：标准分页和排序参数
     • fields、countOnly：标准字段选择和仅计数模式

2. get-collection-by-id

   • 获取单个集合的完整详情，包括产品、规则（智能集合）、SEO 和图片
   • 输入：
     • collectionId（字符串，必填）：集合 ID（例如 gid://shopify/Collection/123 或仅 123）
     • productsFirst（数字，默认值：25）：要包含的产品数量（设为 0 则跳过）
     • fields（数组，可选）：要获取的集合级字段（id、title、handle、descriptionHtml、sortOrder、templateSuffix、updatedAt、productsCount、ruleSet、image、seo）

配置与发现（4 个工具）

1. get-shop-info — 获取商店详情（名称、域名、套餐、货币、时区等）
2. get-metafield-definitions — 分页列出任意所有者类型的元字段定义
3. get-locations — 列出所有有效地点及其地址和配送服务信息
4. get-markets — 列出所有市场及其地区、货币和域名

增强订单与配送（3 个工具）

1. get-order-transactions — 获取订单的付款交易（支付网关、状态、金额、卡片详情）
2. get-fulfillment-orders — 获取订单的配送订单（行项目、分配的地点、状态）
3. get-order-refund-details — 获取订单的退款历史（行项目、金额、补货情况）

库存与定价（4 个工具）

另请参阅库存管理下的 inventory-set-quantities。

1. get-inventory-levels — 获取商品在各地点的库存水平
2. get-inventory-items — 获取产品的库存商品信息（成本、跟踪、原产国）
3. get-price-lists — 列出包含固定价格和数量规则的价格表
4. get-product-variants-detailed — 获取详细的变体信息（库存、定价、图片、元字段）

订单查询筛选器参考

get-orders 工具的 query 参数支持 Shopify 搜索语法：

筛选器	示例
name	name:#77235
created_at	created_at:>2024-01-01 或 created_at:2024-01-01..2024-03-31
updated_at	updated_at:>2024-06-01
financial_status	financial_status:paid
fulfillment_status	fulfillment_status:shipped
status	status:open
email	email:[email protected]
tag / tag_not	tag:vip tag_not:wholesale
discount_code	discount_code:SUMMER20
sku	sku:PROD-001
risk_level	risk_level:high
gateway	gateway:shopify_payments
test	test:true

调试

如果遇到问题，请检查 Claude Desktop 的 MCP 日志。

macOS：

tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

Windows（PowerShell）：

Get-Content "$env:APPDATA\Claude\logs\mcp*.log" -Tail 20 -Wait

常见原因：

• “Access denied for … field”：应用缺少某个权限范围。请参阅身份验证下的权限范围表，然后发布新版本的应用，在应用商店中批准该版本，并重启服务。
• 工具未显示：编辑配置后，完全退出并重启 Claude Desktop。

发布

当版本更新提交到 main 后，.github/workflows/publish.yml 会自动发布：

1. 在你的 PR 中，更新 package.json 中的 version，以及 server.json 中的两个 version 字段（它们必须一致，否则工作流会失败）。
2. 合并到 main。工作流会发布到 npm（附带来源证明），发布到 MCP Registry，并创建 vX.Y.Z GitHub 版本。

未更改版本的合并不会触发发布。

致谢

本项目基于以下项目的成果构建：

• GeLi2001/shopify-mcp：最初的 Shopify MCP 服务
• lucasjahn/shopify-mcp：最初项目的一个分支，新增了字段选择、仅计数模式和许多只读工具

感谢这两个项目及其贡献者。

许可证

MIT。请参阅 LICENSE。原始版权声明予以保留。