使用说明

Shopify MCP服务器——AWS Lambda

无服务器模型上下文协议 Shopify服务器，部署在AWS Lambda上，具有REST API网关、API密钥认证和DynamoDB令牌缓存。使用Shopify Admin GraphQL API（版本 2026-01)通过客户端凭据OAuth。

特性

44种工具，涵盖产品、订单、客户、库存、收款、元字段、履行、定价等
双层身份验证（API网关密钥+Shopify客户端凭据）
DynamoDB中的令牌缓存，具有自动TTL到期功能
可选的自定义域支持
为基于浏览器的客户端启用CORS
通过API网关使用计划的费率限制和每日配额

Shopify应用程序设置

1.在Shopify合作伙伴仪表板中创建应用程序

首选 partners.shopify.com 登录（或创建一个免费的合作伙伴帐户）。
在左侧边栏中，单击应用 → 创建应用程序.
选择 手动创建应用程序.
输入名称（例如。 Shopify MCP Server)然后单击创建.

2.获取客户端ID和客户端密码

创建应用程序后，您将登陆 应用程序概述 页面。
在左侧边栏中，单击 客户端凭证.
复制 客户端ID 和 客户端密钥 --MCP配置需要两者。

3.配置访问范围

此MCP服务器使用 客户端凭证 OAuth流（无头，无用户交互）。您需要配置应用程序请求的范围。

在您的应用程序设置中，转到配置.
在...之下 访问范围，单击配置 “管理API集成”旁边。
添加以下范围：

范围	原因
`read_products`	列出并阅读产品、变体、选项
`write_products`	创建、更新、删除产品和变体
`read_orders`	列出并阅读订单、交易、退款
`write_orders`	更新订单、取消、关闭/重新打开、标记为已付款
`read_customers`	列出并阅读客户
`write_customers`	创建、更新、删除、合并客户
`read_inventory`	读取库存项目和级别
`write_inventory`	设置库存数量
`read_fulfillments`	读取履行订单
`write_fulfillments`	创建实现
`read_draft_orders`	阅读订单草稿
`write_draft_orders`	创建并完成订单草稿
`read_locales`	阅读店铺区域设置
`read_shipping`	读取配送/地点信息
`read_price_rules`	阅读价格表
`read_publications`	阅读收藏和出版物
`read_markets`	读取市场配置

点击保存.

4.申请受保护的客户数据访问（如果需要）

某些范围涉及敏感的客户数据（姓名、电子邮件、地址、电话号码）。Shopify要求应用程序申请访问受保护的客户数据。

在您的应用程序设置中，转到 API访问 → 受保护的客户数据访问.
点击 请求访问.
您需要提供：
- 访问数据的原因（例如“通过MCP协议进行服务器端订单管理和客户支持”）。
- 您需要哪些特定的数据字段：名字, 电子邮件, 电话, 地址.
- 如何存储和保护数据。
- 您的隐私政策URL。
提交请求。Shopify通常会在几个工作日内进行审核。
在获得批准之前，返回受保护客户字段的API调用将对这些字段进行编辑。

注：如果您只使用产品/库存/收集工具，不需要客户个人身份信息，则可以跳过此步骤。

5.启用客户端凭据授予

必须为您的应用显式启用客户端凭据流：

在您的应用程序设置中，转到配置.
在...之下 访问范围，确保选择“客户端凭据”作为管理API集成下的授予类型。
这允许应用程序进行身份验证，而无需商家进行OAuth重定向。

6.在您的应用商店安装应用程序

在合作伙伴仪表板中，转到您的应用程序→ 测试你的应用程序.
选择要安装的存储区（必须是开发存储区或您有员工访问权限的存储区）。
点击 安装应用 并批准所请求的范围。
或者，您可以生成安装链接：
```
https://{your-store}.myshopify.com/admin/oauth/install?client_id={YOUR_CLIENT_ID}
```
登录商店管理员时打开此URL并批准安装。

安装后，客户端凭据流将适用于该存储。

认证

第1层：API网关API密钥

每个请求都必须包括 x-api-key 头球API网关在请求到达Lambda之前对此进行验证。没有有效密钥的请求将获得 403 Forbidden 从网关本身。

第2层：Shopify客户端凭据

每个请求都必须包含以下标题以及您的Shopify凭据：

标题	描述
`x-shopify-client-id`	您的Shopify应用程序客户端ID
`x-shopify-client-secret`	您的Shopify应用程序客户端密码
`x-shopify-shop-domain`	您的店铺域名（例如。 `your-store.myshopify.com`)

这些用于通过以下方式获得Shopify访问令牌 client_credentials OAuth流。令牌以TTL（到期前5分钟的安全裕度）缓存在DynamoDB中。凭据经过SHA-256哈希处理，用于DynamoDB密钥查找——原始机密永远不会被存储。

先决条件

Node.js >=20.x
地形 >= 1.5
AWS CLI配置了适当的凭据
具有自定义应用程序的Shopify合作伙伴帐户（请参阅 Shopify应用程序设置以上）

部署

# Install dependencies
npm install

# Initialize and deploy infrastructure
cd terraform
terraform init
terraform apply

要使用自定义域，请执行以下操作：

terraform apply \
  -var='custom_domain=mcp.example.com' \
  -var='certificate_arn=arn:aws:acm:eu-central-1:123456789:certificate/abc-123'

使用自定义域申请后，创建一个CNAME DNS记录，将您的域指向 custom_domain_target 输出值。

检索API密钥

API密钥值在Terraform输出中被标记为敏感。要查看它：

terraform output api_key_value

MCP客户端配置

基罗

复制 mcp.json.example 到 .kiro/settings/mcp.json （工作空间级别）或 ~/.kiro/settings/mcp.json （用户级别）并填写您的值：

{
  "mcpServers": {
    "shopify-mcp": {
      "type": "streamable-http",
      "url": "https://your-api-id.execute-api.eu-central-1.amazonaws.com/mcp/mcp",
      "headers": {
        "x-api-key": "your-api-gateway-key",
        "x-shopify-client-id": "your-shopify-client-id",
        "x-shopify-client-secret": "your-shopify-client-secret",
        "x-shopify-shop-domain": "your-store.myshopify.com",
        "Content-Type": "application/json"
      }
    }
  }
}

替换：

your-api-id.execute-api.eu-central-1.amazonaws.com 使用您的实际API网关端点（来自 terraform output api_endpoint)
your-api-gateway-key 钥匙从 terraform output api_key_value
your-shopify-client-id 和 your-shopify-client-secret 使用Shopify应用程序中的值（请参阅步骤2)
your-store.myshopify.com 使用您商店的myshopify.com域名

如果使用自定义域，请将URL替换为 https://your-custom-domain.com/mcp.

其他MCP客户端

任何支持以下功能的MCP客户端 streamable-http 运输可以连接。服务器期望：

POST 请求与 Accept: text/event-stream SSE响应的标题
Shopify凭据和API密钥作为HTTP头传递
标准JSON-RPC 2.0消息格式

紧凑模式（令牌优化）--默认值

默认情况下，服务器以紧凑模式公开工具，将44个工具合并为6类工具。这大大减少了AI客户端的输入令牌使用。要单独获取所有44个工具（原始行为），请添加 x-tool-mode: full 头球

分类工具	封面
`shopify-products`	产品、变体、选项、库存
`shopify-orders`	订单、草稿订单、履行、退款
`shopify-customers`	客户、地址、合并
`shopify-collections`	收藏
`shopify-shop`	店铺信息、位置、市场、价目表、图元字段、标签
`shopify-describe`	按需返回任何操作的完整inputSchema

每个类别工具都接受 { "action": "<action-name>", "arguments": { ... } }模型可以调用 shopify-describe 使用操作名称在调用之前获取完整的参数模式。

MCP配置示例（默认为紧凑模式，不需要额外的标头）：

{
  "mcpServers": {
    "shopify-mcp": {
      "type": "streamable-http",
      "url": "https://your-api-id.execute-api.eu-central-1.amazonaws.com/mcp/mcp",
      "headers": {
        "x-api-key": "your-api-gateway-key",
        "x-shopify-client-id": "your-shopify-client-id",
        "x-shopify-client-secret": "your-shopify-client-secret",
        "x-shopify-shop-domain": "your-store.myshopify.com",
        "Content-Type": "application/json"
      }
    }
  }
}

要使用完整模式（单独使用所有44个工具），请添加 "x-tool-mode": "full" 到标题。

请求格式

# List available tools
curl -X POST https://<api-id>.execute-api.<region>.amazonaws.com/mcp/mcp \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-shopify-client-id: YOUR_CLIENT_ID" \
  -H "x-shopify-client-secret: YOUR_CLIENT_SECRET" \
  -H "x-shopify-shop-domain: your-store.myshopify.com" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

# Call a tool
curl -X POST https://<api-id>.execute-api.<region>.amazonaws.com/mcp/mcp \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-shopify-client-id: YOUR_CLIENT_ID" \
  -H "x-shopify-client-secret: YOUR_CLIENT_SECRET" \
  -H "x-shopify-shop-domain: your-store.myshopify.com" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "get-products",
      "arguments": { "limit": 5 }
    }
  }'

可用工具（44）

工具从自动加载 tools/ 启动时的目录。

商店

工具	说明
`get-shop-info`	获取店铺配置，包括名称、计划、货币、功能、付款设置、税务配置和联系信息
`get-locations`	获取所有库存/履行地点及其地址、功能和活动状态
`get-markets`	获取所有市场及其地区、货币、状态和网络存在配置

产品

工具	说明
`get-products`	获取所有产品或按标题搜索
`get-product-by-id`	按ID获取特定产品
`get-product-variants-detailed`	获取产品的所有变量字段：定价、库存、条形码、重量、税码、所选选项、图元字段和图像
`create-product`	创建新产品（使用 `manage-product-variants` 之后创建所有带有价格的真实变体）
`update-product`	更新现有产品的字段（标题、描述、状态、标签等）
`delete-product`	删除产品
`manage-product-options`	创建、更新或删除产品选项（例如尺寸、颜色）
`manage-product-variants`	创建或更新产品变体（省略变体id以创建新变体，包含id以更新现有变体）
`delete-product-variants`	从产品中删除一个或多个变体

订单

工具	说明
`get-orders`	通过可选的状态过滤功能获取订单
`get-order-by-id`	按ID获取特定订单
`get-order-transactions`	获取订单的所有付款交易，包括授权、捕获、退款和作废
`get-order-refund-details`	获取订单的详细退款信息，包括退款项目、金额、补货状态和相关交易
`update-order`	用新信息更新现有订单
`order-cancel`	取消订单，包括退款、重新进货和客户通知选项
`order-close-open`	关闭或重新打开订单
`order-mark-as-paid`	将订单标记为已支付（适用于手动/离线支付）
`create-draft-order`	为电话/聊天销售、发票或批发创建订单草案
`complete-draft-order`	完成订单草稿，将其转换为真实订单
`refund-create`	为订单创建全额或部分退款，并可选择重新进货和运费退款

客户

工具	说明
`get-customers`	获取客户或按姓名/电子邮件搜索
`get-customer-by-id`	通过ID获取单个客户
`get-customer-orders`	获取特定客户的订单
`create-customer`	创建新客户
`update-customer`	更新客户信息
`delete-customer`	删除客户
`manage-customer-address`	创建、更新或删除客户的邮寄地址（可设置为默认）
`customer-merge`	将两条客户记录合并为一条（可选择覆盖要保留的字段）

满足

工具	说明
`create-fulfillment`	使用可选的跟踪信息和客户通知创建订单（将商品标记为已发货）
`get-fulfillment-orders`	获取给定订单的履行订单，包括状态、分配的位置和行项目

库存

工具	说明
`get-inventory-items`	获取产品所有变体的库存项目详细信息，包括SKU、成本、跟踪状态、原产国和HS编码
`get-inventory-levels`	获取库存物品的每个位置的库存数量（可用、在手、已承诺、预留、到货、损坏等）
`inventory-set-quantities`	为特定位置的物品设置绝对库存数量

集合

工具	说明
`get-collections`	查询集合（手动和智能），可选过滤
`get-collection-by-id`	获取一个包含完整细节的集合，包括产品、智能集合规则、搜索引擎优化和图像

元字段

工具	说明
`get-metafield-definitions`	发现任何资源类型（PRODUCT、ORDER、CUSTOMER等）的自定义图元字段定义
`get-metafields`	获取任何Shopify资源（产品、订单、客户、变体、集合等）的图元字段
`set-metafields`	在任何Shopify资源上设置图元字段（原子创建或更新多达25个图元字段）
`delete-metafields`	通过指定所有者ID、命名空间和密钥从任何Shopify资源中删除图元字段

定价

工具	说明
`get-price-lists`	获取所有价格表及其货币、固定/相对调整和相关目录上下文

基础设施

资源	详细信息
上需要API网关	REST API、API密钥 `POST /mcp`，CORS飞行前打开 `OPTIONS /mcp`
使用计划	速率限制：20请求/秒，突发：50，每日配额：10000
Lambda	Node.js 20.x，256 MB内存，30秒超时
DynamoDB	支付_请求，存储哈希凭证→ 带TTL的访问令牌
自定义域	可选，具有ACM证书的区域端点

项目结构

├── index.js                  # Lambda handler — MCP JSON-RPC router
├── lib/
│   ├── crypto.js             # SHA-256 credential hashing
│   ├── helpers.js            # GraphQL response helpers
│   ├── shopifyAuth.js        # Client credentials OAuth flow + caching
│   ├── shopifyClient.js      # GraphQL client factory (API version 2026-01)
│   └── tokenStore.js         # DynamoDB get/put for cached tokens
├── tools/
│   ├── registry.js           # Auto-loads all tool modules
│   └── *.js                  # Individual tool implementations
├── terraform/
│   ├── main.tf               # Lambda, API Gateway, DynamoDB, IAM, custom domain
│   ├── variables.tf          # Configurable inputs (region, domain, memory, etc.)
│   └── outputs.tf            # Endpoint URLs, API key, resource names
├── mcp.json.example          # MCP client config template
└── package.json

安全

在网关级别验证的API密钥（没有它就永远无法到达Lambda）
Shopify凭据经过SHA-256哈希处理，用于DynamoDB密钥查找——原始机密从未存储
默认情况下，DynamoDB在静止时加密（AWS拥有的密钥）
shopDomain 经过验证 *.myshopify.com 模式
通过API网关使用计划的费率限制和每日配额
最低权限IAM（仅限Lambda GetItem/PutItem 在令牌表上）
令牌缓存包括到期前5分钟的安全裕度

地形变量

变量	默认值	描述
`aws_region`	`eu-central-1`	部署到的AWS区域
`project_name`	`shopify-mcp`	所有资源名称的前缀
`lambda_runtime`	`nodejs20.x`	Lambda运行时
`lambda_timeout`	`30`	Lambda超时（秒）
`lambda_memory`	`256`	Lambda内存（MB）
`custom_domain`	`""`	可选自定义域（例如。 `mcp.example.com`)
`certificate_arn`	`""`	ACM证书ARN（如果需要 `custom_domain` 已设置）

地形输出

输出	描述
`api_endpoint`	默认API网关终结点URL
`custom_domain_endpoint`	自定义域终结点（如果已配置）
`custom_domain_target`	DNS记录的CNAME目标（如果已配置）
`api_key_id`	API密钥ID
`api_key_value`	API密钥值（敏感-使用 `terraform output api_key_value` 查看）
`lambda_function_name`	Lambda函数名称
`dynamodb_table_name`	DynamoDB表名