Shopify AI Toolkit 使用指南

Shopify AI Toolkit 是 Shopify 官方提供的 AI 开发增强套件：把你的 AI 助手（Cursor、Claude Code、VS Code、Gemini CLI、Codex 等）与 Shopify 文档、API Schema、代码校验能力 以及 CLI 侧与店铺相关的执行能力 连接起来，让智能体按平台真实行为工作，而不是凭训练数据「猜」接口怎么写。

定位说明：官方文档归类在 Apps → Build → Dev tools 下，主要面向 Shopify 应用与扩展 开发场景。若你主要做 主题与 Liquid，可搭配阅读 AI 辅助与主题工程化；Toolkit 与 Theme Check、CLI 仍可共用同一套编辑器习惯。

一、Toolkit 解决什么问题

痛点	Toolkit 的作用
模型编造不存在的 Admin API 字段或 GraphQL 操作名	通过官方文档与 Schema 约束回答与生成
团队各自问 ChatGPT，答案版本不一致	统一插件 / Skills / MCP 入口，随官方更新
写完代码不知道是否符合平台习惯	结合校验与 CLI 能力，减少「能跑但不符合规范」的代码

官方表述：让 agent 与 Shopify 正确协作，而不是猜测实现细节。（参见 Shopify AI Toolkit 文档。）

二、安装前要求

根据官方说明，安装前应满足：

Node.js：18 及以上（建议与团队 CLI 版本对齐，使用 LTS）。
受支持的 AI 工具之一：Claude Code、Codex（仅支持 Skills 与 MCP）、Cursor、Gemini CLI、Visual Studio Code。

具体子版本与兼容性以官方 Requirements 为准。

三、三种安装方式概览

方式	适用场景	维护方式
插件（Plugin，推荐）	希望「一次装好、自动跟新」	插件随官方发布更新
Agent Skills（手动）	只想要部分能力、可自选技能包	需自行拉取更新
Dev MCP Server	已在工作流里深度使用 MCP、希望接本地 stdio 服务	本地 `npx` 拉起，按文档配置各客户端

下面分方式说明要点；命令与菜单位置以你本机文档版本为准，若与官方不一致，请以 shopify.dev AI Toolkit 为准。

四、方式 A：插件安装（推荐）

插件把能力打成一个整体，官方推荐优先用插件，以便新能力发布时自动带上。

Claude Code

在 Claude Code 中启用 Shopify 插件市场（官方示例命令）：
/plugin marketplace add Shopify/shopify-ai-toolkit
再安装插件：
/plugin install shopify-plugin@shopify-plugin

Cursor

在 Cursor Marketplace 中搜索并添加 Shopify 相关官方插件（详见官方文档「Cursor」小节）。

Gemini CLI

在终端执行（官方提供的扩展安装方式）：


gemini extensions install https://github.com/Shopify/shopify-ai-toolkit

Visual Studio Code

在 VS Code 设置中启用 Agent plugins 相关预览能力（以当前 VS Code 版本说明为准）。
命令面板执行 Chat: Install Plugin From Source。
仓库地址填入：https://github.com/Shopify/shopify-ai-toolkit（与官方文档一致）。

五、方式 B：Agent Skills（`npx skills`）

适合希望 按需安装、或只引入部分技能（例如仅 Admin GraphQL）的团队。

安装全部技能（示例）：


npx skills add Shopify/shopify-ai-toolkit

仅安装单个技能（示例，以官方技能名为准）：


npx skills add Shopify/shopify-ai-toolkit --skill shopify-admin

完整技能列表见官方 GitHub 仓库说明。注意：手动添加的 Skills 不会自动更新，需要你们自行跟进版本。

六、方式 C：Dev MCP Server（`@shopify/dev-mcp`）

通过 MCP（Model Context Protocol） 把本地或 IDE 里的助手接到 Shopify 开发者资源；官方说明该 MCP 在本地运行，且文档描述为 无需额外认证（以官方最新说明为准）。

通用思路

使用 npx -y @shopify/dev-mcp@latest 作为 MCP 子进程命令；
在各客户端的 MCP 配置 里增加 shopify-dev-mcp（名称可自定）；
保存配置后重启对应客户端，使 MCP 生效。

Cursor 配置示例

在 Cursor → Settings → Cursor Settings → Tools and MCP → New MCP server 中增加类似配置（与官方 Cursor 小节对齐）：


{
  "mcpServers": {
    "shopify-dev-mcp": {
      "command": "npx",
      "args": ["-y", "@shopify/dev-mcp@latest"]
    }
  }
}

若 Windows 上出现连接错误，官方文档提供了改用 cmd /k npx ... 的替代写法，请在文档中复制最新片段。

Claude Code 示例

官方建议通过 CLI 注册 MCP，例如：


claude mcp add --transport stdio shopify-dev-mcp -- npx -y @shopify/dev-mcp@latest

执行后 重启 Claude Code。

Codex CLI

在 ~/.codex/config.toml 中增加 [mcp_servers.shopify-dev-mcp] 段（注意 Codex 使用 snake_case 的 mcp_servers，与部分 JSON 配置不同）。完整片段见官方 Codex 说明。

Gemini CLI 与 VS Code

Gemini CLI：在 settings.json 的 mcpServers 中增加与上文类似的 command / args；跨项目使用可加官方文档中的 --scope user 等参数。
VS Code：命令面板打开 MCP: Open User Configuration，在用户级 mcp.json 的 servers 下添加 shopify-dev-mcp 条目（字段名以 VS Code 当前 MCP 规范为准）。

七、与日常开发流程如何配合

应用脚手架：仍使用 shopify app init 等 CLI 流程（参见 Shopify 应用开发）。
写 Admin API / GraphQL 前：让已连接 Toolkit / MCP 的助手 对照 Schema 生成查询，减少字段名错误。
合并前：继续跑你们团队的 Lint、单测、Theme Check（主题相关时），Toolkit 不替代 CI。
密钥与合规：Toolkit 提升的是「文档与接口正确性」；API Token、客户数据 仍须遵守安全最佳实践与公司政策，勿粘贴进不可信会话。

八、延伸阅读与官方入口

官方主文档：Shopify AI Toolkit
相关： Shopify CLI · Scaffold an app · Storefront MCP
本站： Shopify 应用开发 · AI 辅助与主题工程化 · 独立站与 AI：热点能力地图 · Storefront MCP 简介

提示：Shopify 对插件市场、MCP 字段名与 VS Code 行为会迭代更新；若本文与 shopify.dev 当前页不一致，以官方页面为准。