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