MCP 設定指南

將 Shopify MCP 伺服器連接到每個主要 AI 程式碼工具的逐步說明。每份指南涵蓋安裝、設定、驗證和疑難排解。

建議設定

為獲得最佳的 Shopify 開發體驗，請設定兩個 MCP 伺服器：

Shopify Dev MCP —— 文件、API schema、Liquid 參考（不需認證）
Shopify Store MCP —— 透過 Admin API 進行即時商店管理（需要存取權杖）

本指南涵蓋這兩者。

先決條件

在開始任何設定之前，請確保您具備：

Node.js 18+ —— 從 nodejs.org 下載
npm 9+ —— 隨 Node.js 附帶
Shopify Partner 帳號 —— 免費註冊
開發商店 —— 從您的 Partner 儀表板建立

驗證您的 Node.js 安裝：

node --version   # Should output v18.x.x or higher
npm --version    # Should output 9.x.x or higher
npx --version    # Should output 9.x.x or higher

建立 Shopify 存取權杖

對於商店管理 MCP 伺服器，您需要一個 Admin API 存取權杖：

前往您的 Shopify 商店管理後台
導覽至設定 > 應用程式和銷售通路
點擊開發應用程式（您可能需要先啟用開發者存取權限）
點擊建立應用程式並為其命名，例如「MCP Integration」
點擊設定 Admin API 範圍
選擇您需要的範圍：

範圍	用途
`read_products`、`write_products`	產品管理
`read_orders`、`write_orders`	訂單管理
`read_customers`、`write_customers`	顧客資料
`read_inventory`、`write_inventory`	庫存追蹤
`read_fulfillments`、`write_fulfillments`	出貨處理

點擊儲存然後安裝應用程式
複製 Admin API 存取權杖 —— 您只會看到一次

權杖安全

切勿將您的存取權杖提交到版本控制
切勿在螢幕截圖、聊天或文件中分享權杖
將權杖儲存在環境變數或密鑰管理工具中
定期輪換權杖
使用最小必要的範圍

Claude Code（推薦）

Claude Code 擁有最佳的 MCP 整合，具有內建的伺服器管理指令。

步驟 1：新增 Dev MCP 伺服器

claude mcp add shopify-dev -- npx -y @anthropic-ai/shopify-dev-mcp@latest

步驟 2：新增 Store MCP 伺服器

claude mcp add shopify-store \
  -e SHOPIFY_ACCESS_TOKEN=shpat_xxxxxxxxxxxxx \
  -e MYSHOPIFY_DOMAIN=your-store.myshopify.com \
  -- npx -y shopify-mcp@latest

環境變數替代方案

除了在指令中傳遞權杖，您可以在 shell 設定檔中設定它們：

# Add to ~/.zshrc or ~/.bashrc
export SHOPIFY_ACCESS_TOKEN="shpat_xxxxxxxxxxxxx"
export MYSHOPIFY_DOMAIN="your-store.myshopify.com"

然後在不使用 -e 旗標的情況下新增伺服器：

claude mcp add shopify-store -- npx -y shopify-mcp@latest

伺服器將自動從您的環境中讀取。

步驟 3：驗證

# List configured MCP servers
claude mcp list

# Start Claude Code and test
claude

在 Claude Code 中，嘗試這些提示詞：

# Test Dev MCP
Search the Shopify docs for product creation best practices

# Test Store MCP
List the first 5 products in my store

範圍選項

# Project scope (default) - only available in this project
claude mcp add shopify-dev -- npx -y @anthropic-ai/shopify-dev-mcp@latest

# User scope - available in all projects
claude mcp add --scope user shopify-dev -- npx -y @anthropic-ai/shopify-dev-mcp@latest

管理伺服器

# List all servers
claude mcp list

# Remove a server
claude mcp remove shopify-dev

# View server details
claude mcp get shopify-dev

Cursor

步驟 1：找到設定檔

作業系統	路徑
macOS	`~/.cursor/mcp.json`
Linux	`~/.cursor/mcp.json`
Windows	`%APPDATA%\Cursor\mcp.json`

如果檔案不存在，請建立它。

步驟 2：新增伺服器設定

{
  "mcpServers": {
    "shopify-dev": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/shopify-dev-mcp@latest"]
    },
    "shopify-store": {
      "command": "npx",
      "args": ["-y", "shopify-mcp@latest"],
      "env": {
        "SHOPIFY_ACCESS_TOKEN": "shpat_xxxxxxxxxxxxx",
        "MYSHOPIFY_DOMAIN": "your-store.myshopify.com"
      }
    }
  }
}

步驟 3：重新啟動 Cursor

儲存設定檔後，完全重新啟動 Cursor（不僅是重新載入視窗）。

步驟 4：驗證

開啟 Composer 面板（Cmd+I / Ctrl+I）
尋找 MCP 伺服器圖示（通常是扳手或插頭圖示）
點擊它以查看可用工具
嘗試查詢：「Search Shopify docs for webhook topics」

Cursor 專屬技巧

Cursor 在首次啟動時可能需要 10-15 秒來初始化 MCP 伺服器
如果工具未出現，請檢查 Cursor 輸出面板中的 MCP 相關錯誤
使用 Cursor 的 .cursorrules 檔案與 MCP 一起添加 Shopify 專屬上下文

Claude Desktop

macOS 設定

步驟 1：開啟設定檔

# Create the config directory if needed
mkdir -p ~/Library/Application\ Support/Claude

# Open or create the config file
open -a TextEdit ~/Library/Application\ Support/Claude/claude_desktop_config.json

步驟 2：新增設定

{
  "mcpServers": {
    "shopify-dev": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/shopify-dev-mcp@latest"]
    },
    "shopify-store": {
      "command": "npx",
      "args": ["-y", "shopify-mcp@latest"],
      "env": {
        "SHOPIFY_ACCESS_TOKEN": "shpat_xxxxxxxxxxxxx",
        "MYSHOPIFY_DOMAIN": "your-store.myshopify.com"
      }
    }
  }
}

步驟 3：重新啟動 Claude Desktop

完全退出並重新開啟 Claude Desktop。

步驟 4：驗證

在聊天輸入框中尋找鐵鎚圖示。點擊它以查看可用的 MCP 工具。

Windows 設定

步驟 1：開啟設定檔

# Open or create the config file
notepad "$env:APPDATA\Claude\claude_desktop_config.json"

步驟 2：新增設定

使用與上方 macOS 相同的 JSON 設定。

步驟 3：重新啟動並驗證

重新啟動 Claude Desktop 並檢查鐵鎚圖示。

Windows 專屬注意事項

Windows PATH 問題

如果在 Windows 上找不到 npx，請指定完整路徑：

{
  "mcpServers": {
    "shopify-dev": {
      "command": "C:\\Program Files\\nodejs\\npx.cmd",
      "args": ["-y", "@anthropic-ai/shopify-dev-mcp@latest"]
    }
  }
}

Codex (OpenAI)

OpenAI 的 Codex CLI 支援 MCP 伺服器用於工具增強。

步驟 1：安裝 Codex

npm install -g @openai/codex

步驟 2：新增 MCP 伺服器

# Add Dev MCP
codex mcp add shopify-dev -- npx -y @anthropic-ai/shopify-dev-mcp@latest

# Add Store MCP
codex mcp add shopify-store \
  -e SHOPIFY_ACCESS_TOKEN=shpat_xxxxxxxxxxxxx \
  -e MYSHOPIFY_DOMAIN=your-store.myshopify.com \
  -- npx -y shopify-mcp@latest

步驟 3：驗證

codex mcp list
codex  # Start Codex and test with a Shopify query

Codex 專屬注意事項

Codex 處理工具呼叫的方式可能與基於 Claude 的客戶端不同
在建構複雜工作流程之前，先個別測試每個工具
一些社群 MCP 伺服器可能與 Codex 有相容性上的細微差異

Windsurf

步驟 1：找到設定

Windsurf 在其設定中儲存 MCP 設定。開啟設定（Cmd+, / Ctrl+,）並搜尋「MCP」，或找到 MCP 設定檔：

作業系統	路徑
macOS	`~/.windsurf/mcp.json`
Linux	`~/.windsurf/mcp.json`
Windows	`%APPDATA%\Windsurf\mcp.json`

步驟 2：新增設定

{
  "mcpServers": {
    "shopify-dev": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/shopify-dev-mcp@latest"]
    },
    "shopify-store": {
      "command": "npx",
      "args": ["-y", "shopify-mcp@latest"],
      "env": {
        "SHOPIFY_ACCESS_TOKEN": "shpat_xxxxxxxxxxxxx",
        "MYSHOPIFY_DOMAIN": "your-store.myshopify.com"
      }
    }
  }
}

步驟 3：重新啟動並驗證

重新啟動 Windsurf 並確認 MCP 工具出現在 AI 面板中。

Cline

Cline（VS Code 擴充功能）透過其設定支援 MCP 伺服器。

步驟 1：開啟 Cline 設定

在已安裝 Cline 的 VS Code 中：

開啟命令面板（Cmd+Shift+P / Ctrl+Shift+P）
搜尋「Cline: MCP Servers」
或直接編輯設定檔

設定檔位置：

作業系統	路徑
macOS	`~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
Linux	`~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
Windows	`%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`

步驟 2：新增設定

{
  "mcpServers": {
    "shopify-dev": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/shopify-dev-mcp@latest"],
      "disabled": false
    },
    "shopify-store": {
      "command": "npx",
      "args": ["-y", "shopify-mcp@latest"],
      "env": {
        "SHOPIFY_ACCESS_TOKEN": "shpat_xxxxxxxxxxxxx",
        "MYSHOPIFY_DOMAIN": "your-store.myshopify.com"
      },
      "disabled": false
    }
  }
}

步驟 3：驗證

重新載入 VS Code（Cmd+Shift+P > 「Developer: Reload Window」）
開啟 Cline 側邊欄
檢查 MCP 伺服器狀態指示器
測試：「List my Shopify MCP tools」

疑難排解

「Cannot find module」錯誤

Error: Cannot find module '@anthropic-ai/shopify-dev-mcp'

原因和修正方式：

Node.js 版本太舊：

node --version  # Must be 18+
# If outdated, update via nvm:
nvm install 18
nvm use 18

npx 快取損壞：

# Clear npm cache
npm cache clean --force
# Try again
npx -y @anthropic-ai/shopify-dev-mcp@latest

網路/代理問題：

# Test npm registry access
npm ping
# If behind a proxy:
npm config set proxy http://proxy.example.com:8080

伺服器啟動但無工具出現

確認伺服器正在執行：

# Claude Code
claude mcp list
# Look for status: "connected" vs "disconnected"

檢查伺服器日誌：

在 Claude Desktop 中，檢查以下位置的日誌：

macOS：~/Library/Logs/Claude/mcp*.log
Windows：%APPDATA%\Claude\Logs\mcp*.log

常見修正方式： 完全重新啟動 AI 客戶端（不僅是重新載入）。

認證錯誤

Error: 401 Unauthorized

修正方式：

權杖已過期或撤銷： 在 Shopify 管理後台生成新權杖
網域格式錯誤： 使用 your-store.myshopify.com（而非自訂網域）
範圍不足： 檢查您的權杖是否擁有必要的 API 範圍

環境變數未設定：

# Verify the variable is set
echo $SHOPIFY_ACCESS_TOKEN
# If empty, set it:
export SHOPIFY_ACCESS_TOKEN="shpat_xxxxxxxxxxxxx"

速率限制

Error: 429 Too Many Requests

Shopify 的 Admin API 有速率限制（標準方案通常為每秒 40 個請求）。如果您達到速率限制：

降低請求速度 —— 避免快速連續執行批次操作
檢查您的方案 —— Shopify Plus 商店有更高的限制
使用批次操作 —— 一些 MCP 伺服器支援 GraphQL 批次操作來處理大型資料集
監控使用量 —— 檢查回應中的 X-Shopify-Shop-Api-Call-Limit 標頭

伺服器啟動緩慢

使用 npx 的 MCP 伺服器在首次執行時會下載套件。後續執行使用 npm 快取。

加速啟動：

# Pre-install the package globally
npm install -g @anthropic-ai/shopify-dev-mcp
npm install -g shopify-mcp

# Then reference the local binary instead of npx
claude mcp add shopify-dev -- shopify-dev-mcp

多商店

要連接到多個 Shopify 商店，新增個別的 MCP 伺服器條目：

{
  "mcpServers": {
    "shopify-dev": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/shopify-dev-mcp@latest"]
    },
    "store-production": {
      "command": "npx",
      "args": ["-y", "shopify-mcp@latest"],
      "env": {
        "SHOPIFY_ACCESS_TOKEN": "shpat_prod_token",
        "MYSHOPIFY_DOMAIN": "my-store.myshopify.com"
      }
    },
    "store-staging": {
      "command": "npx",
      "args": ["-y", "shopify-mcp@latest"],
      "env": {
        "SHOPIFY_ACCESS_TOKEN": "shpat_staging_token",
        "MYSHOPIFY_DOMAIN": "my-store-staging.myshopify.com"
      }
    }
  }
}

正式環境安全

當同時連接到正式環境和暫存環境的商店時，始終在您的提示詞中指定目標商店。在開發期間，考慮對正式環境的權杖使用唯讀範圍。

伺服器版本衝突

如果在更新後遇到意外行為：

# Clear npm cache and reinstall
npm cache clean --force

# Claude Code: remove and re-add
claude mcp remove shopify-dev
claude mcp add shopify-dev -- npx -y @anthropic-ai/shopify-dev-mcp@latest

# Pin to a specific version if needed
claude mcp add shopify-dev -- npx -y @anthropic-ai/shopify-dev-mcp@1.2.3

設定參考

環境變數

變數	使用者	說明
`SHOPIFY_ACCESS_TOKEN`	Store MCP 伺服器	Admin API 存取權杖
`MYSHOPIFY_DOMAIN`	shopify-mcp (GeLi2001)	商店網域（例如 `store.myshopify.com`）
`SHOP_DOMAIN`	@ajackus/shopify-mcp-server	商店網域
`SHOPIFY_STOREFRONT_TOKEN`	支援 Storefront 的伺服器	Storefront API 權杖
`COMPOSIO_API_KEY`	Composio	Composio 平台金鑰
`ADZVISER_API_KEY`	Adzviser	Adzviser 平台金鑰

傳輸類型

傳輸方式	說明	使用情境
`stdio`	標準 I/O（本地行程）	大多數設定的預設值。伺服器在本地執行。
`streamable-http`	具有串流的 HTTP	遠端/託管的 MCP 伺服器
`sse`	Server-Sent Events（舊版）	較舊的遠端伺服器

大多數社群伺服器使用 stdio 傳輸方式，這意味著伺服器作為由您的 AI 客戶端管理的本地行程執行。不需要連接埠轉發或網路設定。

先決條件​

建立 Shopify 存取權杖​

Claude Code（推薦）​

步驟 1：新增 Dev MCP 伺服器​

步驟 2：新增 Store MCP 伺服器​

步驟 3：驗證​

範圍選項​

管理伺服器​

Cursor​

步驟 1：找到設定檔​

步驟 2：新增伺服器設定​

步驟 3：重新啟動 Cursor​

步驟 4：驗證​

Cursor 專屬技巧​

Claude Desktop​

macOS 設定​

步驟 1：開啟設定檔​

步驟 2：新增設定​

步驟 3：重新啟動 Claude Desktop​

步驟 4：驗證​

Windows 設定​

步驟 1：開啟設定檔​

步驟 2：新增設定​

步驟 3：重新啟動並驗證​

Windows 專屬注意事項​

Codex (OpenAI)​

步驟 1：安裝 Codex​

步驟 2：新增 MCP 伺服器​

步驟 3：驗證​

Codex 專屬注意事項​

Windsurf​

步驟 1：找到設定​

步驟 2：新增設定​

步驟 3：重新啟動並驗證​

Cline​

步驟 1：開啟 Cline 設定​

步驟 2：新增設定​

步驟 3：驗證​

疑難排解​

「Cannot find module」錯誤​

伺服器啟動但無工具出現​

認證錯誤​

速率限制​

伺服器啟動緩慢​

多商店​

伺服器版本衝突​

設定參考​

環境變數​

傳輸類型​

先決條件

建立 Shopify 存取權杖

Claude Code（推薦）

步驟 1：新增 Dev MCP 伺服器

步驟 2：新增 Store MCP 伺服器

步驟 3：驗證

範圍選項

管理伺服器

Cursor

步驟 1：找到設定檔

步驟 2：新增伺服器設定

步驟 3：重新啟動 Cursor

步驟 4：驗證

Cursor 專屬技巧

Claude Desktop

macOS 設定

步驟 1：開啟設定檔

步驟 2：新增設定

步驟 3：重新啟動 Claude Desktop

步驟 4：驗證

Windows 設定

步驟 1：開啟設定檔

步驟 2：新增設定

步驟 3：重新啟動並驗證

Windows 專屬注意事項

Codex (OpenAI)

步驟 1：安裝 Codex

步驟 2：新增 MCP 伺服器

步驟 3：驗證

Codex 專屬注意事項

Windsurf

步驟 1：找到設定

步驟 2：新增設定

步驟 3：重新啟動並驗證

Cline

步驟 1：開啟 Cline 設定

步驟 2：新增設定

步驟 3：驗證

疑難排解

「Cannot find module」錯誤

伺服器啟動但無工具出現

認證錯誤

速率限制

伺服器啟動緩慢

多商店

伺服器版本衝突

設定參考

環境變數

傳輸類型