Shopify MCP Server

Shopify MCP Server

（如果喜欢，请点个星标！）

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

📦 包名称：shopify-mcp 🚀 命令：shopify-mcp（不是 shopify-mcp-server）

功能

• 产品管理：完整的产品、变体和选项 CRUD（8 个工具）
• 客户管理：完整的 CRUD、合并和地址管理（8 个工具）
• 订单管理：智能查找、取消、关闭/重新打开、标记为已付款、履约、退款（10 个工具）
• 元字段管理：获取、设置和删除任意资源上的元字段（3 个工具）
• 库存管理：设置各个地点的绝对库存数量（1 个工具）
• 标签管理：为任意可添加标签的资源添加/移除标签（1 个工具）
• 分页与排序：所有列表查询均支持基于游标的分页和排序键
• 高级筛选：所有列表端点均支持传递 Shopify 查询语法
• GraphQL 集成：直接集成 Shopify 的 GraphQL Admin API（2026-01）
• 全面的错误处理：为 API 和身份验证问题提供清晰的错误消息

前置条件

1. Node.js（版本 18 或更高）
2. 一个 Shopify 店铺及其自定义应用（参见下方设置说明）

设置

身份验证

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

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

自 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
4. 在店铺中安装该应用
5. 从应用的 API 凭据中复制 Client ID 和 Client Secret

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

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

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

在 Claude Desktop 中使用

客户端凭据（推荐）：

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

静态访问令牌（旧版）：

{
  "mcpServers": {
    "shopify": {
      "command": "npx",
      "args": [
        "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 shopify-mcp \
  --clientId YOUR_CLIENT_ID \
  --clientSecret YOUR_CLIENT_SECRET \
  --domain your-store.myshopify.com

静态访问令牌（旧版）：

claude mcp add shopify -- npx 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 shopify-mcp
   

直接安装（可选）

如果你想全局安装此包：

npm install -g shopify-mcp

然后运行：

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

其他选项

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

⚠️ 重要： 如果使用命令行参数时看到“需要 SHOPIFY_ACCESS_TOKEN 环境变量”的错误，你可能安装了其他包。请确认使用的是 shopify-mcp，而不是 shopify-mcp-server。

可用工具（31）

分页、排序与筛选

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

• 基于游标的分页：after / before（游标字符串），响应中包含 pageInfo（hasNextPage、hasPreviousPage、startCursor、endCursor）
• 排序：sortKey（各资源特有的枚举值）和 reverse（布尔值）
• 高级筛选：query 或 searchQuery 参数，接受 Shopify 查询语法

产品管理（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（字符串，可选）：分页游标

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" }]

8. delete-product-variants

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

客户管理（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（字符串，必填）：订单 GID
     • refundLineItems（数组，可选）：要退款的商品项，包含 lineItemId、quantity、restockType（CANCEL/RETURN/NO_RESTOCK）、locationId
     • shipping（对象，可选）：{ amount, fullRefund } 运费退款
     • note（字符串，可选）：退款备注
     • notify（布尔值，可选）：发送退款通知

10. create-draft-order

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

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

1. complete-draft-order

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

Metafield 管理（3 个工具）

1. get-metafields

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

2. set-metafields

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

3. delete-metafields

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

库存管理（1 个工具）

1. inventory-set-quantities

   • 设置特定地点商品的绝对库存数量
   • 输入：
     • reason（字符串，必填）：变更原因（例如 "correction"、"cycle_count_available"）
     • name（字符串，必填）："available" 或 "on_hand"
     • quantities（数组，必填）：商品项，包含 inventoryItemId、locationId、quantity

标签管理（1 个工具）

1. manage-tags

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

订单查询筛选器参考

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 日志：

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

许可证

MIT