Shopify MCP

🚀 Shopify MCP Server

Shopify MCP Server 是一个用于 Shopify API 的服务器，它允许用户通过 GraphQL API 与店铺数据进行交互。该服务器提供了管理产品、客户、订单等功能的工具。

如果你喜欢这个项目，欢迎留下一个 Star！

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

🚀 快速开始

要使用这个 MCP 服务器，你需要在你的 Shopify 商店中创建一个自定义应用，并获取访问令牌。具体步骤如下：

1. 从你的 Shopify 管理界面，转到 设置 > 应用和销售渠道。
2. 点击 开发应用（你可能需要先启用开发者预览）。
3. 点击 创建应用。
4. 为你的应用设置一个名称（例如，“Shopify MCP Server”）。
5. 点击 配置管理 API 权限范围。
6. 选择以下权限范围：
   • read_products, write_products
   • read_customers, write_customers
   • read_orders, write_orders
   • read_content, write_content（用于博客和文章）
7. 点击 保存。
8. 点击 安装应用。
9. 点击 安装 以授予应用访问你的商店数据的权限。
10. 安装完成后，你将看到你的 管理 API 访问令牌。
11. 复制此令牌，你在配置时会用到它。

与 Claude Desktop 一起使用

将以下内容添加到你的 claude_desktop_config.json 文件中：

{
  "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

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

如果你更喜欢使用环境变量而不是命令行参数，可以按照以下步骤操作：

1. 创建一个 .env 文件，并包含你的 Shopify 凭证：

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

2. 使用 npx 运行服务器：

npx shopify-mcp

直接安装（可选）

如果你想全局安装该包，可以使用以下命令：

npm install -g shopify-mcp

然后运行它：

shopify-mcp --accessToken=<YOUR_ACCESS_TOKEN> --domain=<YOUR_SHOP>.myshopify.com

⚠️ 重要提示

如果你在使用命令行参数时看到 “SHOPIFY_ACCESS_TOKEN environment variable is required” 错误，可能是你安装了不同的包。请确保你使用的是 shopify-mcp，而不是 shopify-mcp-server。

✨ 主要特性

• 产品管理：搜索、检索和更新产品信息，包括 SEO 优化内容。
• 客户管理：加载客户数据并管理客户标签。
• 订单管理：高级订单查询和过滤。
• 博客管理：使用自定义模板和评论策略创建、检索和更新博客。
• 文章管理：创建和管理具有丰富内容、作者信息和 SEO 元数据的博客文章。
• 店铺搜索：对产品、文章、博客和页面进行统一搜索。
• GraphQL 集成：直接集成 Shopify 的 GraphQL 管理 API。
• 全面的错误处理：为 API 和认证问题提供清晰的错误消息。
• LLM 优化：专为与 AI 语言模型无缝使用而设计。

📦 安装指南

前提条件

1. Node.js（版本 16 或更高）
2. Shopify 自定义应用访问令牌（请参阅下面的设置说明）

Shopify 访问令牌设置

要使用此 MCP 服务器，你需要在你的 Shopify 商店中创建一个自定义应用：

1. 从你的 Shopify 管理界面，转到 设置 > 应用和销售渠道。
2. 点击 开发应用（你可能需要先启用开发者预览）。
3. 点击 创建应用。
4. 为你的应用设置一个名称（例如，“Shopify MCP Server”）。
5. 点击 配置管理 API 权限范围。
6. 选择以下权限范围：
   • read_products, write_products
   • read_customers, write_customers
   • read_orders, write_orders
   • read_content, write_content（用于博客和文章）
7. 点击 保存。
8. 点击 安装应用。
9. 点击 安装 以授予应用访问你的商店数据的权限。
10. 安装完成后，你将看到你的 管理 API 访问令牌。
11. 复制此令牌，你在配置时会用到它。

💻 使用示例

产品管理

get-products

获取产品或按标题搜索产品，支持基于游标导航的分页。

// 获取第一页产品
{
  "limit": 10
}

// 使用上一个响应中的 endCursor 获取下一页
{
  "limit": 10,
  "after": "endCursor_from_previous_response"
}

// 使用当前响应中的 startCursor 获取上一页
{
  "limit": 10,
  "before": "startCursor_from_current_response"
}

// 带分页的产品搜索
{
  "searchTitle": "t-shirt",
  "limit": 5,
  "after": "cursor_from_previous_response"
}

// 以相反顺序获取产品
{
  "limit": 10,
  "reverse": true
}

get-product-by-id

按 ID 获取特定产品的所有详细信息。

{
  "productId": "gid://shopify/Product/1234567890"
}

update-product

更新产品的任何方面，包括基本信息、SEO 和变体。

// 更新产品标题和状态
{
  "productId": "gid://shopify/Product/1234567890",
  "title": "Awesome T-Shirt",
  "status": "ACTIVE"
}

// 更新 SEO 信息
{
  "productId": "gid://shopify/Product/1234567890",
  "seo": {
    "title": "Awesome T-Shirt | 100% Cotton | Available in 5 Colors",
    "description": "High-quality cotton t-shirt perfect for everyday wear. Available in multiple colors and sizes."
  }
}

// 更新产品变体
{
  "productId": "gid://shopify/Product/1234567890",
  "variants": [
    {
      "id": "gid://shopify/ProductVariant/1234567",
      "price": "29.99",
      "compareAtPrice": "39.99",
      "inventoryPolicy": "DENY"
    }
  ]
}

// 一次性更新多个方面
{
  "productId": "gid://shopify/Product/1234567890",
  "title": "Premium Cotton T-Shirt",
  "vendor": "Fashion Basics",
  "productType": "Apparel",
  "tags": ["cotton", "t-shirt", "basics", "summer"],
  "seo": {
    "title": "Premium Cotton T-Shirt | Fashion Basics | Multiple Colors",
    "description": "Experience comfort with our premium cotton t-shirt. Perfect for any occasion."
  },
  "variants": [
    {
      "id": "gid://shopify/ProductVariant/1234567",
      "price": "29.99",
      "compareAtPrice": "39.99"
    }
  ]
}

update-product-image-alt-text

更新特定产品图片的替代文本。

{
  "productId": "gid://shopify/Product/1234567890",
  "imageId": "gid://shopify/MediaImage/123",
  "altText": "New alt text for the image"
}

博客和文章管理

create-article

在指定博客中创建新文章。

// 创建一篇已发布的文章，包含格式化内容
{
  "blogId": "gid://shopify/Blog/123456789",
  "title": "My New Article",
  "content": "<p>Article content with <strong>HTML formatting</strong>.</p>",
  "author": {
    "name": "John Doe"
  },
  "published": true,
  "tags": ["news", "updates"]
}

// 创建一篇草稿文章，用于未来发布
{
  "blogId": "gid://shopify/Blog/123456789",
  "title": "Upcoming Article",
  "content": "<p>Draft content...</p>",
  "author": {
    "name": "Jane Smith"
  },
  "published": false,
  "tags": ["draft"]
}

店铺搜索

search-shopify

对产品、文章、博客和页面进行统一搜索。

// 搜索关于 "kawaii" 的文章和博客
{
  "query": "kawaii",
  "types": ["ARTICLE", "BLOG"],
  "first": 5
}

// 搜索所有内容类型
{
  "query": "new collection",
  "first": 10
}

页面管理

update-page

更新现有页面的详细信息。

// 更新页面内容和 SEO
{
  "pageId": "gid://shopify/Page/123456789",
  "title": "About Our Store",
  "bodyHtml": "<h1>Welcome!</h1><p>Learn about our story...</p>",
  "seo": {
    "title": "About Us - Kawaii Store",
    "description": "Discover our journey in bringing kawaii culture to you"
  }
}

集合管理

update-collection

更新现有集合的详细信息。

// 更新集合并进行 SEO 优化
{
  "collectionId": "gid://shopify/Collection/123456789",
  "title": "Summer Kawaii Collection",
  "descriptionHtml": "<p>Discover our cutest summer items!</p>",
  "seo": {
    "title": "Summer Kawaii Collection 2025",
    "description": "Explore our adorable summer collection featuring..."
  }
}

📚 详细文档

内容管理最佳实践

SEO 优化

• 使用描述性标题和 URL 友好的句柄。
• 为所有内容提供元描述。
• 自然地包含相关关键字。
• 保持 URL 简洁且有意义。
• 在 HTML 内容中使用适当的标题层次结构。

内容组织

• 将相关产品分组到集合中。
• 使用一致的命名约定。
• 保持清晰的内容层次结构。
• 保持产品描述详细准确。
• 使用高质量的图片并提供描述性替代文本。

性能考虑

• 优化图片大小。
• 使用适当的查询限制。
• 缓存频繁访问的内容。
• 尽可能批量更新。
• 监控 API 使用情况。

内容管理提示

• 定期进行内容审核。
• 所有内容保持一致的品牌形象。
• 采用移动友好的格式。
• 定期备份重要内容。
• 对重大更改进行版本控制。

错误处理

所有工具都包含全面的错误处理，包括：

• 无效 ID 错误
• 权限错误
• 速率限制错误
• 验证错误
• 网络错误

错误响应包括：

• 错误代码
• 导致错误的字段
• 详细的错误消息
• 解决建议

API 限制

速率限制

• 遵守 Shopify 的 API 速率限制。
• 使用适当的查询限制。
• 为失败的请求实现重试逻辑。
• 监控 API 使用情况。

内容限制

• 最大内容长度
• 支持的 HTML 标签
• 图片大小限制
• API 版本兼容性

认证

• 所需的访问权限范围
• 令牌过期
• IP 限制
• 应用权限

博客和文章管理重要注意事项

处理博客内容

• 始终先使用 get-blogs 获取有效的博客 ID。
• 使用 get-blog-by-id 获取特定博客的详细信息。
• 更新博客时，只包含你要修改的字段。
• commentPolicy 只能设置为 "MODERATED" 或 "CLOSED"。

处理文章

• 文章必须与现有博客关联。
• 使用 get-articles 列出特定博客中的文章。
• 创建或更新文章时，body 字段支持 HTML 内容。
• 作者信息应始终至少包含姓名。
• 标签区分大小写，并且在文章中应保持一致。
• 图片 URL 必须公开可访问。
• 句柄创建是可选的 - 如果未提供，Shopify 将从标题生成一个。

文章创建最佳实践

• 为文章内容使用语义 HTML（例如，<p>、<h2>、<ul> 等）。
• 保持文章摘要简洁（建议：150 - 160 个字符）。
• 使用一致的标签命名约定。
• 在创建文章之前始终验证博客 ID。
• 撰写标题和内容时考虑 SEO 影响。
• 先在测试环境中测试 HTML 格式。
• 对于草稿，设置 published: false 以保存而不发布。
• 使用标签时，保持一致的分类法。
• 为任何图片提供描述性替代文本。
• 使用发布日期策略性地安排文章。
• 保持 HTML 内容干净且结构良好。
• 使用有意义的句柄以获得更好的 SEO。
• 格式化内容时考虑移动设备的可读性。

文章创建提示

• HTML 内容：content 字段接受 HTML 标记以实现丰富的格式：

<p>First paragraph with <strong>bold text</strong>.</p>
<h2>Section Heading</h2>
<ul>
  <li>List item one</li>
  <li>List item two</li>
</ul>

• 标签：使用描述性、一致的标签以实现更好的组织：

"tags": ["product-updates", "how-to", "tips"]

• 草稿模式：通过设置 published: false 创建未发布的草稿：

{
  "published": false,
  // 其他字段...
}

• 作者信息：始终提供完整的作者详细信息：

"author": {
  "name": "Full Author Name"
}