Shopify Store Front MCP Server

Shopify店面MCP服务器

该服务器通过MCP提供对Shopify Storefront API的访问，允许AI助手查询您的Shopify商店数据并与之交互。

特性

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

安装说明

1. 克隆此存储库
2. 安装依赖项： pip install -r requirements.txt
3. 复制 .env.example 到 .env 并配置您的环境变量
4. 通过Shopify Admin生成Storefront API代币（见下文）
5. 运行服务器： python -m shopify_storefront_mcp_server

环境变量

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

# 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

生成店面API令牌

1. 登录您的Shopify管理员
2. 首选 应用程序和销售渠道 > 开发应用程序 > 创建应用程序
3. 命名您的应用程序（例如，“MCP店面”）
4. 首选 API证书 > 配置店面API作用域
5. 选择必要的范围：

- unauthenticated_read_product_listings - unauthenticated_read_product_inventory - unauthenticated_read_product_pricing - unauthenticated_write_checkouts - unauthenticated_read_content

1. 保存并复制生成的Storefront API访问令牌
2. 将令牌添加到您的 .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：客户的收货地址（包括地址1、地址2、城市、州、邮政编码、国家）
• customer://billing_address：客户的账单地址（包括地址1、地址2、城市、州、邮政编码、国家）
• 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")

这个整合的工具通过为所有客户数据操作提供一致的界面简化了与人工智能助手的集成，包括标准客户信息和可能对个性化有用的任何自定义字段。

数据隐私和存储

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

• user_data/customer.json.example：显示具有虚拟数据的预期结构的模板文件
• 条目在 .gitignore 防止实际客户数据的意外提交

部署此服务器时 user_data/customer.json 当 customer_data 首先使用工具。您还可以复制并重命名示例文件以开始：

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

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

使用客户数据创建结账

该服务器通过组合以下功能，可以轻松创建包含客户信息的Shopify签出 customer_data 和 shopify_storefront_graphql 工具。

工作流程示例：

# 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 } }"}'

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

安全考虑

• 永远不要承诺你的 .env 文件或包含API令牌的任何文件
• 对所有敏感信息使用环境变量
• 考虑在Shopify管理员中设置IP限制
• 查看授予您的Storefront API令牌的权限