Shopify Dev MCP 服务器

Shopify Dev MCP 服务器（@anthropic-ai/shopify-dev-mcp）是 Shopify 和 Anthropic 合作构建的官方 MCP 服务器。它为 AI 编码工具提供对 Shopify 开发者文档、GraphQL Admin API schema、主题验证等的直接访问。这是对 Shopify 开发最具影响力的单个 MCP 服务器。

它提供什么

Shopify Dev MCP 服务器不连接到你的商店。相反，它提供 开发智能——AI 编写正确 Shopify 代码所需的知识：

GraphQL schema 自省：查询 Admin API schema 以发现类型、字段、变更及其精确签名
开发者文档搜索：搜索 Shopify 官方文档并检索相关文章
入门指南：访问各种 Shopify 开发路径的结构化入门内容
主题验证：对你的主题文件运行 Shopify Theme Check
Checkout 可扩展性工具：访问 Checkout 特定的文档和模式

不需要商店访问权限

此服务器不需要 Shopify 访问令牌或商店凭据。它提供开发者知识，而非商店数据。对于商店数据操作（产品、订单等的 CRUD），你需要下一节介绍的社区 MCP 服务器。

安装

Claude Code

推荐的安装方式是在用户范围内注册服务器，使其在所有项目中可用：

为 Claude Code 安装（全局）
claude mcp add shopify-dev-mcp -s user -- npx -- -y @anthropic-ai/shopify-dev-mcp@latest

仅为特定项目安装：

为特定项目安装
claude mcp add shopify-dev-mcp -- npx -- -y @anthropic-ai/shopify-dev-mcp@latest

验证安装：

验证 MCP 服务器
claude mcp list

你应该在输出中看到 shopify-dev-mcp，传输方式为 stdio。

Cursor

将以下内容添加到你的 Cursor MCP 设置（项目根目录或全局设置中的 .cursor/mcp.json）：

.cursor/mcp.json
{
  "mcpServers": {
    "shopify-dev-mcp": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/shopify-dev-mcp@latest"]
    }
  }
}

Claude Desktop

添加到你的 Claude Desktop 配置文件：

claude_desktop_config.json
{
  "mcpServers": {
    "shopify-dev-mcp": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/shopify-dev-mcp@latest"]
    }
  }
}

配置文件位置因操作系统而异：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Codex (OpenAI)

Codex 也支持使用相同配置格式的 MCP 服务器：

Codex MCP 配置
{
  "mcpServers": {
    "shopify-dev-mcp": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/shopify-dev-mcp@latest"]
    }
  }
}

始终使用 @latest

@latest 标签确保你获得最新版本，包含更新的文档和 schema 数据。Shopify 的 API 随每个季度版本更新而演进，MCP 服务器也会相应更新。

可用工具

introspect_admin_schema

服务器中最强大的工具。它让你可以查询 Shopify 的 GraphQL Admin API schema 以发现类型、字段、参数及其精确签名。

使用场景：

在编写查询前发现某类型上可用的字段
检查变更的输入要求
查找字段的正确枚举值
理解类型关系（connections、edges、nodes）

示例：发现产品字段
> What fields are available on the Shopify Product type in the
  Admin API? Use the MCP schema introspection tool.

Claude Code 调用 introspect_admin_schema 并返回包含类型、描述和弃用通知的完整字段列表。

示例：检查变更签名
> What are the required inputs for the productCreate mutation?
  Introspect the Admin API schema.

Schema 版本意识

自省的 schema 反映特定的 API 版本。如果你使用的是旧的 API 版本，某些字段或变更可能不可用。始终与你项目的目标 API 版本进行交叉参考。

search_dev_docs

搜索 Shopify 的官方开发者文档并返回相关文章、指南和 API 参考。

使用场景：

查找特定 Shopify 功能的文档
查找 Webhook、认证或计费的最佳实践
发现你不知道的新 API 或功能
获取复杂功能的实施指导

示例：搜索 Webhook 文档
> Search the Shopify developer docs for information about
  mandatory webhooks and GDPR compliance requirements.

示例：查找计费 API 文档
> Search Shopify docs for how to implement app billing
  with usage-based charges using the GraphQL API.

get_started

为不同的 Shopify 开发路径提供结构化的入门内容。在启动新类型的项目时特别有用。

使用场景：

了解新扩展类型的设置流程
理解 Hydrogen 的开发工作流
获取 Remix 应用的推荐项目结构

示例：开始使用 Functions
> Use the get_started tool to learn about building Shopify
  Functions for order discounts.

validate_theme

对你的主题文件运行 Shopify Theme Check，识别 Liquid 代码问题、性能问题和最佳实践违规。

使用场景：

在部署前验证主题代码
在 API 版本升级后查找 Liquid 弃用
识别性能问题（缺少懒加载、过大的 DOM）
检查无障碍合规性

示例：验证主题
> Validate the theme files in this project using the Shopify
  theme validation tool. Report any errors or warnings.

与 Claude Code 的文件访问结合

Claude Code 可以在单个工作流中读取你的主题文件并通过 MCP 验证它们。让它"修复所有主题验证错误"，它会验证、识别问题、编辑文件并重新验证——全部自动完成。

Checkout MCP 工具

Shopify Dev MCP 包含用于 Checkout 可扩展性的专用工具：

Checkout UI 扩展模式：Checkout UI 扩展的常见模式
Checkout 验证：验证 Checkout 扩展配置
支付定制：支付方式过滤和定制的工具
配送定制：运费修改模式

示例：Checkout 扩展帮助
> Use the checkout MCP tools to understand how to implement
  a post-purchase upsell extension with React.

最佳实践

使用会话 ID

在对 MCP 服务器进行多个相关查询时，会话上下文有助于提供更相关的结果。Claude Code 在一个会话中自动处理此问题，但请注意 /clear 会重置此上下文。

上下文关联的后续查询
> Search docs for Shopify Functions
# 第一个查询建立上下文

> Now show me the specific input query format for delivery customization
# 后续查询利用会话上下文获得更精确的结果

组合工具以获得最大效果

当你在单个工作流中组合多个 MCP 工具时，真正的力量就会显现：

组合工作流
> I need to write a GraphQL mutation to update product metafields.
  1. Introspect the Admin API schema for the metafieldsSet mutation
  2. Search the docs for metafield best practices
  3. Then write the mutation with proper TypeScript types

Claude Code 会调用 introspect_admin_schema 获取精确的变更签名，调用 search_dev_docs 获取最佳实践，然后将两者综合成正确的、结构良好的代码。

OPT_OUT_INSTRUMENTATION 环境变量

Shopify Dev MCP 服务器默认收集匿名使用遥测数据以改进工具。如果你想退出：

退出遥测
# Set environment variable before launching Claude Code
export OPT_OUT_INSTRUMENTATION=1
claude

或者永久添加到你的 shell 配置文件：

永久退出
echo 'export OPT_OUT_INSTRUMENTATION=1' >> ~/.zshrc
source ~/.zshrc

你也可以直接在 MCP 服务器注册时配置它：

注册时退出遥测
claude mcp add shopify-dev-mcp -s user -e OPT_OUT_INSTRUMENTATION=1 -- npx -- -y @anthropic-ai/shopify-dev-mcp@latest

遥测是匿名的

遥测数据仅包含工具使用模式（哪些工具被调用、调用频率）——不包含你的代码、提示或商店数据。它帮助 Shopify 和 Anthropic 优先改进 MCP 服务器。

使用 Shopify Dev MCP 的常见工作流

工作流 1：编写新的 GraphQL 查询

分步操作
1. "Introspect the Admin API schema for the OrderConnection type"
2. "What filters are available on the orders query?"
3. "Write a paginated query to fetch orders with fulfillment status
    UNFULFILLED from the last 7 days"

工作流 2：构建主题版块

分步操作
1. "Search docs for section schema best practices in OS 2.0"
2. "Validate the current theme for any existing issues"
3. "Create a new testimonials section following the patterns
    from the docs"
4. "Validate the theme again to ensure no new issues"

工作流 3：调试 API 错误

分步操作
1. "Search docs for error code ACCESS_DENIED on Admin API"
2. "Introspect the schema for the mutation that's failing
    to check if the required scope changed"
3. "What scopes are needed for the productUpdate mutation?"

故障排除

服务器无法启动

调试 MCP 服务器启动
# Test the server directly
npx -y @anthropic-ai/shopify-dev-mcp@latest

# Check for npm/Node issues
node --version  # Must be 18+
npm --version

# Clear npm cache if needed
npm cache clean --force

工具未显示

如果你已注册服务器但工具没有显示：

重新注册服务器
# Remove and re-add
claude mcp remove shopify-dev-mcp
claude mcp add shopify-dev-mcp -s user -- npx -- -y @anthropic-ai/shopify-dev-mcp@latest

# Restart Claude Code
claude

响应缓慢

启动 Claude Code 后的第一次调用可能会很慢，因为 MCP 服务器需要初始化（下载并启动 npx 包）。同一会话中的后续调用会很快。

需要网络连接

Shopify Dev MCP 服务器需要网络访问来获取文档和 schema 数据。它在离线或隔离环境中无法工作。如果你在企业代理后面，请确保 npx 可以访问 npm 注册表和 Shopify 的文档端点。

下一步

Shopify Dev MCP 服务器提供开发知识。要对你的 Shopify 商店执行实际操作（创建产品、管理订单等），你需要连接商店的 MCP 服务器。继续学习 Shopify Store MCP 服务器来设置商店数据访问。

它提供什么​

安装​

Claude Code​

Cursor​

Claude Desktop​

Codex (OpenAI)​

可用工具​

introspect_admin_schema​

search_dev_docs​

get_started​

validate_theme​

Checkout MCP 工具​

最佳实践​

使用会话 ID​

组合工具以获得最大效果​

OPT_OUT_INSTRUMENTATION 环境变量​

使用 Shopify Dev MCP 的常见工作流​

工作流 1：编写新的 GraphQL 查询​

工作流 2：构建主题版块​

工作流 3：调试 API 错误​

故障排除​

服务器无法启动​

工具未显示​

响应缓慢​

下一步​

它提供什么

安装

Claude Code

Cursor

Claude Desktop

Codex (OpenAI)

可用工具

introspect_admin_schema

search_dev_docs

get_started

validate_theme

Checkout MCP 工具

最佳实践

使用会话 ID

组合工具以获得最大效果

OPT_OUT_INSTRUMENTATION 环境变量

使用 Shopify Dev MCP 的常见工作流

工作流 1：编写新的 GraphQL 查询

工作流 2：构建主题版块

工作流 3：调试 API 错误

故障排除

服务器无法启动

工具未显示

响应缓慢

下一步