Shopify Storefront MCP Server

Shopify Storefront MCP 服务

此服务器通过 MCP 提供 Shopify Storefront API 访问权限，让 AI 助手能够查询和交互您的 Shopify 商店数据。

功能

• 访问商品、商品系列和库存数据
• 创建和管理购物车
• 支持 GraphQL 查询和变更
• 自动处理和验证令牌
• 轻松集成兼容 MCP 的 AI 助手

设置说明

1. 克隆此仓库
2. 安装依赖项：pip install -r requirements.txt
3. 将 .env.example 复制为 .env 并配置环境变量
4. 通过 Shopify 管理后台生成 Storefront API 令牌（见下文）
5. 运行服务器：python -m shopify_storefront_mcp_server

环境变量

使用提供的 .env.example 作为模板创建 .env 文件：

# Required
SHOPIFY_STOREFRONT_ACCESS_TOKEN=your_storefront_token
SHOPIFY_STORE_NAME=your-store-name

# Optional
SHOPIFY_API_VERSION=2025-04
SHOPIFY_BUYER_IP=127.0.0.1

生成 Storefront API 令牌

1. 登录 Shopify 管理后台
2. 前往 应用和销售渠道 > 开发应用 > 创建应用
3. 为应用命名（例如，“MCP Storefront”）
4. 前往 API 凭据 > 配置 Storefront API 范围
5. 选择所需范围：
   • unauthenticated_read_product_listings
   • unauthenticated_read_product_inventory
   • unauthenticated_read_product_pricing
   • unauthenticated_write_checkouts
   • unauthenticated_read_content
6. 保存并复制生成的 Storefront API 访问令牌
7. 将令牌添加到 .env 文件中，变量名为 SHOPIFY_STOREFRONT_ACCESS_TOKEN

使用示例

使用 MCP 服务器运行：

python -m shopify_storefront_mcp_server

服务器提供以下 MCP 工具：

• shopify_discover：检测 URL 是否属于 Shopify 店面并发现身份验证令牌
• shopify_storefront_graphql：针对 Storefront API 执行 GraphQL 查询
• customer_data：用于所有客户数据操作（创建、读取、更新、删除）的统一工具

客户资源

此服务器还为客户信息提供 MCP 资源：

• customer://name：客户全名
• customer://email：客户电子邮件地址
• customer://phone：客户电话号码
• customer://shipping_address：客户的收货地址（包括 address1、address2、city、state、postal_code、country）
• customer://billing_address：客户的账单地址（包括 address1、address2、city、state、postal_code、country）
• customer://profile：完整的客户资料

客户数据存储在 user_data/customer.json 中，应使用 customer_data 工具进行管理。

管理客户数据

服务器提供统一的 customer_data 工具，用于管理所有客户信息。此工具将创建、读取、更新和删除操作整合到一个界面中。

示例：

# Get all customer data
customer_data(operation="get")

# Get a specific field
customer_data(operation="get", field="name")
customer_data(operation="get", field="shipping_address")

# Update a specific field
customer_data(operation="update", field="name", value="Jane Doe")
customer_data(
    operation="update",
    shipping_address={
        "address1": "123 Main St",
        "address2": "Apt 4B",
        "city": "New York",
        "state": "NY",
        "postal_code": "10001",
        "country": "US"
    }
)

# Add custom fields
customer_data(
    operation="update",
    custom_fields={
        "preferences": {
            "theme": "dark",
            "notifications": "email",
            "language": "en-US"
        },
        "loyalty_tier": "gold",
        "last_purchase_date": "2023-06-15"
    }
)

# Get a custom field
customer_data(operation="get", field="preferences")
customer_data(operation="get", field="loyalty_tier")

# Update single custom field
customer_data(operation="update", field="loyalty_tier", value="platinum")

# Delete a specific field
customer_data(operation="delete", field="phone")
customer_data(operation="delete", field="preferences")

# Delete all customer data
customer_data(operation="delete")

此整合工具为所有客户数据操作（包括标准客户信息以及任何有助于个性化的自定义字段）提供一致的界面，从而简化与 AI 助手的集成。

数据隐私与存储

客户数据存储在 user_data/customer.json 中。此文件包含个人信息，不应提交到版本控制中。仓库包含：

• user_data/customer.json.example：模板文件，展示了包含虚拟数据的预期结构
• .gitignore 中的条目，用于防止意外提交实际客户数据

部署此服务器时，首次使用 customer_data 工具会自动创建 user_data/customer.json 文件。您也可以复制并重命名示例文件以开始使用：

cp user_data/customer.json.example user_data/customer.json

客户文件中存储的所有数据都会在服务器重启后保留。该文件支持标准客户字段（姓名、电子邮件、地址）以及用于 AI 个性化的任意自定义字段。

使用客户数据创建结账

通过结合使用 customer_data 和 shopify_storefront_graphql 工具，该服务器可以轻松创建包含客户信息的 Shopify 结账。

示例工作流：

# Step 1: Get customer data
customer_profile = customer_data(operation="get")

# Step 2: Create a cart with GraphQL
cart_mutation = """
mutation createCart($lines: [CartLineInput!]!) {
  cartCreate(input: {lines: $lines}) {
    cart {
      id
      checkoutUrl
    }
    userErrors {
      field
      message
    }
  }
}
"""

cart_variables = {
  "lines": [
    {
      "merchandiseId": "gid://shopify/ProductVariant/12345678901234",
      "quantity": 1
    }
  ]
}

cart_result = shopify_storefront_graphql(
  mode="execute",
  host="your-store.myshopify.com",
  token="your_storefront_token",
  query=cart_mutation,
  variables=cart_variables
)

# Step 3: Apply customer attributes to the cart
cart_id = # extract from cart_result
customer_info = json.loads(customer_profile)

attributes_mutation = """
mutation updateCartAttributes($cartId: ID!, $attributes: [AttributeInput!]!) {
  cartAttributesUpdate(cartId: $cartId, attributes: $attributes) {
    cart {
      id
      checkoutUrl
    }
    userErrors {
      field
      message
    }
  }
}
"""

attributes_variables = {
  "cartId": cart_id,
  "attributes": [
    {
      "key": "email",
      "value": customer_info["email"]
    },
    {
      "key": "deliveryAddress",
      "value": json.dumps(customer_info["shipping_address"])
    }
  ]
}

shopify_storefront_graphql(
  mode="execute",
  host="your-store.myshopify.com",
  token="your_storefront_token",
  query=attributes_mutation,
  variables=attributes_variables
)

这种方法让你可以完全掌控结账流程，同时利用已存储的客户信息。

故障排除

如果遇到身份验证错误：

1. 验证令牌格式：Storefront API 令牌应以 shpsa_（较新）或 shpat_（较旧）开头
2. 检查商店名称：确保 SHOPIFY_STORE_NAME 正确（不包含 .myshopify.com）
3. 检查 API 版本：确保该 API 版本受支持
4. 测试令牌：使用 cURL 直接测试令牌：

   curl -X POST \
     https://your-store.myshopify.com/api/2025-04/graphql.json \
     -H "Content-Type: application/json" \
     -H "X-Shopify-Storefront-Access-Token: your_token" \
     -d '{"query": "query { shop { name } }"}'
   

5. 重新生成令牌：如果问题仍然存在，请创建一个具有正确作用域的新令牌

安全注意事项

• 切勿提交 .env 文件或任何包含 API 令牌的文件
• 对所有敏感信息使用环境变量
• 考虑在 Shopify Admin 中设置 IP 限制
• 检查授予 Storefront API 令牌的权限