MCP 设置指南

为每个主要 AI 编码工具连接 Shopify MCP 服务器的分步说明。每个指南涵盖安装、配置、验证和故障排除。

推荐设置

为了获得最佳 Shopify 开发体验，请配置两个 MCP 服务器：

Shopify Dev MCP -- 文档、API 架构、Liquid 参考（无需认证）
Shopify Store MCP -- 通过 Admin API 进行实时商店管理（需要访问令牌）

本指南涵盖两者。

前提条件

在开始任何设置之前，请确保你已具备：

Node.js 18+ -- 从 nodejs.org 下载
npm 9+ -- 随 Node.js 一起安装
Shopify 合作伙伴账户 -- 免费注册
开发商店 -- 从合作伙伴控制面板创建

验证你的 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 并检查 AI 面板中是否出现 MCP 工具。

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" 错误

服务器启动但工具未显示

认证错误

速率限制

服务器启动缓慢

多商店

服务器版本冲突

配置参考

环境变量

传输类型