shopify-multi-store

Shopify Multi-Store MCP

一个 MCP 服务，连接所有 Shopify 店铺。

通过 Claude、ChatGPT、Codex、Cursor、VS Code 和其他 MCP 客户端，查询、比较和报告 Shopify 店铺数据，并进行受保护的更新。

演示 · 快速开始 · 报告 · AI 客户端 · 安全模型

版本 2.0

可在本地运行，也可为团队托管一个服务：每个人都使用自己的 Shopify 员工账号登录，并从 Claude、ChatGPT、Codex 或任何远程 MCP 客户端连接。每个人能执行的操作由 Shopify 自身的员工权限决定。内置引导式 Admin 工作流、ShopifyQL 报告、架构验证，以及可用于任何 Admin 变更的通用操作接口。 请参阅功能覆盖范围和验收要求。 目前尚未验证与 Shopify ChatGPT 的完全一致性。

查看运行效果

演示使用的是示例店铺和示例数据。服务会将每个真实店铺的凭据分开保存。

快速开始

安装服务、连接店铺并运行健康检查：

npm install --global shopify-multi-store-mcp-server
shopify-multi-store setup
shopify-multi-store doctor

Claude Code 用户可以用一条命令添加服务：

claude mcp add shopify-multi-store -- npx -y shopify-multi-store-mcp-server start

每个店铺都有一个永久别名和单独的安全凭据。每次店铺操作都必须指定该别名。

功能一览

此服务器与 Shopify Dev MCP

这两个服务器解决的是不同的问题。当 Agent 需要 Shopify 参考资料并访问你的店铺时，请同时使用它们。

Shopify Dev MCP 可帮助 Agent 创建和检查 Shopify 代码。此服务器则会对选定店铺执行获批的操作。

现成报告

shopify_report 会针对选定的店铺运行一份只读报告。将 report 设置为以下选项之一：

若要跨店铺搜索商品，请使用 shopify_search，并设置 resource: "products" 和 stores。

可以尝试以下提示词：

• “为每个已连接的店铺生成一份组合概览。”
• “汇总过去 30 天的订单和当前订单金额。不同货币分开显示。”
• “显示零售和批发店铺中的低库存、零库存和负库存。”
• “显示在此店铺缺货、但在其他店铺有库存的商品。”
• “在每个店铺中查找 SKU A123，并比较其状态、价格和库存。”
• “在每个店铺中搜索与蛋白质相关的商品。”
• “按逾期时长分组，显示逾期两天以上尚未履行的订单。”
• “查找在一个店铺中处于启用状态、但在另一个店铺中缺失或处于草稿状态的商品。”
• “查找这些店铺中的价格差异和重复 SKU。”
• “比较零售和批发店铺中 SKU A123 和 B456 的库存。”
• “列出三个店铺过去七天内尚未履行的订单。”
• “审计商品目录健康状况，并显示缺少 SEO 或媒体数据的商品。”
• “比较这些店铺中的启用商品目录和精选系列。”

连接 AI 客户端

此服务适用于支持本地 stdio MCP 服务的客户端。如果客户端支持 Agent Skills，Agent Skills 可改善工具选择。

claude mcp add shopify-multi-store -- npx -y shopify-multi-store-mcp-server start

mkdir -p ~/.claude/skills/shopify-multi-store
cp skills/shopify-multi-store/SKILL.md ~/.claude/skills/shopify-multi-store/SKILL.md

{
  "mcpServers": {
    "shopify-multi-store": {
      "command": "npx",
      "args": ["-y", "shopify-multi-store-mcp-server", "start"]
    }
  }
}

{
  "servers": {
    "shopify-multi-store": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "shopify-multi-store-mcp-server", "start"]
    }
  }
}

为团队托管

默认方式是在自己的电脑上本地使用（如上所述）。托管是可选的：想要共享服务的人可以运行一个服务，团队成员则通过自己已在使用的 AI 应用连接，不限方案：Claude（个人自定义连接器）、ChatGPT、Codex、Claude Code、Cursor、VS Code、Gemini CLI、Windsurf，或任何支持远程服务的 MCP 客户端。

每个人都使用自己的 Shopify 员工账号登录，每次调用都使用该用户自己的 Shopify 权限：Shopify 决定他们可以执行的操作，服务端不设置角色或策略文件。Shopify 令牌保存在服务端并经过加密。重新连接最多每天一次，即可一键连接所有商店。每次工具调用都会被审计。

托管方式有两种，均由想要共享服务的人自行托管：

• Cloudflare Workers： 请参阅 docs/DEPLOY-CLOUDFLARE.md 中的分步说明：创建 Shopify 应用，设置四个密钥，进行部署，然后在 AI 应用中添加 MCP URL。
• 任意服务器：运行 shopify-multi-store serve（或使用随附的 Dockerfile），并分享 https://<host>/mcp。

请参阅从 AI 应用连接了解各客户端的操作步骤，参阅 docs/HOSTED.md了解设置方法，并参阅 docs/ACTIONS.md了解各用户的访问权限和通用操作工具。

商店身份验证

授权码设置使用 http://127.0.0.1:3456/oauth/callback。请先将其添加为允许的重定向 URL。

默认授权码作用域为只读。请仅授予任务所需的 Admin API 作用域。

连接第一个店铺

每个店铺都需要一个别名（由小写字母、数字和连字符组成，例如 main），以及永久的 *.myshopify.com 域名。店铺管理员可在 Settings > Domains 下查看该域名。凭据取决于获取 Admin API 访问权限的方式。Shopify 现在会在 Dev Dashboard 中创建新应用；在店铺管理员中创建的自定义应用，在原有位置仍可继续使用。

使用 Dev Dashboard 应用（新设置）：

1. 打开 Dev Dashboard（dev.shopify.com），选择 Apps > Create app，并为应用命名（例如 “Multi-Store MCP”）。
2. 创建一个版本。在 access scopes 下添加所需权限范围。read_products,read_orders,read_inventory,read_locations,read_customers 涵盖只读工具；如需查看工具可执行的全部操作所需的权限范围，请运行 node "$(npm root -g)/shopify-multi-store-mcp-server/scripts/print-scopes.mjs" --full 输出完整列表，并移除应用未获批准的权限范围。使用授权码方式时，还需添加重定向 URL http://127.0.0.1:3456/oauth/callback。
3. 发布该版本，然后从 Dev Dashboard 将应用安装到店铺，并批准权限范围。
4. 从应用设置中复制客户端 ID 和客户端密钥。
5. 运行 shopify-multi-store oauth。如果店铺与应用位于同一个 Shopify 组织中，选择 client-credentials；否则选择 authorization-code（此时会打开浏览器以供批准）。输入别名、*.myshopify.com 域名、客户端 ID 和客户端密钥。使用客户端凭据时，服务会自行获取和刷新令牌。

使用在店铺管理员中创建的自定义应用：

1. 在店铺管理员中，打开 Settings > Apps（部分管理员中为 Apps and sales channels）> Develop apps，然后打开你的应用。如果管理员仍提供此选项，也可以在那里创建应用。
2. 在 Configuration 下为 Admin API 设置所需的权限范围，然后安装应用。
3. 在 API credentials 下显示 Admin API 访问令牌（以 shpat_ 开头；Shopify 只会显示一次）。
4. 运行 shopify-multi-store setup，并输入别名、*.myshopify.com 域名和令牌。

然后运行 shopify-multi-store doctor 检查每个店铺，并对其他店铺重复上述步骤。密钥会存储在操作系统凭据存储区中，不会写入配置文件。

管理店铺

shopify-multi-store list
shopify-multi-store doctor
shopify-multi-store remove store-alias

shopify-multi-store import /absolute/path/to/stores.json

该服务提供 29 个工具。

只读操作可以并行运行。变更操作仅针对所选商店执行。

所有引导式写入工具默认使用 dryRun: true，返回变更前后（或将创建内容）的预览，不会进行任何修改；用户授权确切的商店和变更后，传入 dryRun: false 即可应用变更。随后，工具会读取结果。产品、订单和客户的标签通过 addTags 和 removeTags 更改；replaceTags 会替换所有标签，预览中会列出将移除的标签。写入结果不会因过大而被丢弃：对于大型结果，会进行截断，同时保留状态、计数以及所有未应用的条目。

shopify_graphql_mutation 和 shopify_run_action 会拒绝列入拒绝名单的 mutation；对于具有破坏性的 mutation（包括仅因参数而具有破坏性的 mutation，例如将产品状态设为 ARCHIVED），必须将 confirm 设置为 mutation 名称。

通用操作工具

三个工具可调用 Shopify Admin API 中的所有变更操作（API 2026-04 中共 514 个），包括其中没有专用工具的 483 个：

拒绝列表会阻止创建凭据或更改应用自身账单的变更操作。使用 node scripts/print-scopes.mjs --full 请求完整的权限范围集。有关示例和第三方应用无法执行的操作，请参阅 docs/ACTIONS.md。

Shopify 配套技能

安装 Shopify 官方的 shopify 技能：

shopify-multi-store install-shopify-skills

该命令会为其检测到的每个受支持的 Agent 安装此技能。传入 --agent <name> 可选择一个 Agent，例如 --agent claude-code。

shopify 技能包含一个路由表。其 admin 主题用于搜索 Shopify 文档并验证自定义 Admin GraphQL 操作；shopifyql 主题涵盖销售额、收入、订单、转化和趋势分析。Shopify toolkit 2.0.0 将原有的 shopify-admin 和 shopify-shopifyql 技能合并为此技能；toolkit 的 ucp 技能（购物命令行工具）不包含在此安装中。

如果 Shopify 再次重命名该技能，命令会以状态码 1 退出，打印 toolkit 附带的技能，并显示用于按名称安装技能的 npx skills add 命令。若未安装任何内容，命令绝不会报告成功。

此服务仍负责控制商店选择、凭据、执行和变更授权。Shopify 的技能脚本默认会发送使用情况遥测数据。

设置 OPT_OUT_INSTRUMENTATION=true 可关闭此遥测功能。

此集成使用官方的 Shopify AI Toolkit。它也借鉴了 Shopify Admin Skills 中的实用模式。

安全模型

机密信息不会进入主配置文件。

配置中存储别名、域名、API 版本和非机密的 OAuth 客户端 ID。默认路径为 ~/.config/codex-shopify-multi-store/stores.json。

codex-shopify-multi-store 这一名称在该路径和凭据存储的服务名称中均有使用，是项目早期版本遗留下来的名称。为确保现有安装仍能使用其商店和凭据，此名称会保留；它并不表示此服务仅适用于 Codex。

设置 SHOPIFY_MULTI_STORE_CONFIG 可使用其他配置路径。

• 切勿提交访问令牌、OAuth 客户端机密、.env 文件或包含凭据的配置文件。
• 仅授予任务所需的 Shopify Admin API 权限范围。
• 每次执行变更操作前，确认目标商店。
• 漏洞报告请参阅 SECURITY.md。

Linux 凭据存储需要 Secret Service 提供程序，例如 GNOME Keyring 或 KWallet。

其他安装选项

无需全局安装即可运行健康检查：

npx -y shopify-multi-store-mcp-server doctor

直接从 GitHub 安装（npm 会运行 prepare 脚本来构建服务）：

npm install --global github:alex-brecher/shopify-multi-store

开发

git clone https://github.com/alex-brecher/shopify-multi-store.git
cd shopify-multi-store
npm ci
npm test
npm run test:live
npm pack --dry-run

实时测试使用已配置的商店，并且只会调用 Shopify Admin API 的只读接口。

许可证

MIT

请阅读更新日志、贡献指南、安全政策和目录提交指南。