@marketbasketanalysis/mcp

一个 MCP 服务器，让任何 AI 代理都能访问来自电商商家订单历史的真实共同购买洞察和商家运营工具。19 个工具，涵盖发现、捆绑、洞察、补货、商家运营和高级挖掘。可与 Claude Desktop、Claude Code、Cursor、Windsurf、Cline、OpenAI Agent SDK 以及任何支持 MCP stdio 协议的主机配合使用。适用于 Shopify、BigCommerce、WooCommerce、Magento 和 OroCommerce 上的商家。有关哪些工具可覆盖自托管后端，请参阅下文“平台覆盖范围”。

一个 npm 包服务于每个市场。该服务器与平台无关，它是一个 HTTP 客户端，通过公共 REST API 调用商店的 MBA 后端。只需一个开关（MBA_API_BASE，见下文）即可将整个服务器重新指向任何商店。大多数工具适用于全部五个平台；少数工具依赖的后端路由并非每个平台都已提供。每个工具的市场覆盖情况见工具目录的“市场”列。

为什么需要它

当顾客问 AI 购物助手“这个健身背包搭配什么好？”时，助手应基于商家真实的订单数据给出实际答案，而不是泛泛的“你可能也喜欢”式猜测。当商家问 Claude“这周我应该做些什么？”时，助手应从一份按优先级排序的周计划中提取，而不是凭空编造任务。这个服务器只需一行配置，就能让这两种流程适用于任何 MCP 主机。

5 行安装（Claude Desktop）

{
  "mcpServers": {
    "marketbasketanalysis": {
      "command": "npx",
      "args": ["-y", "@marketbasketanalysis/mcp"],
      "env": { "MBA_API_KEY": "mba_live_YOUR_KEY_HERE" }
    }
  }
}

将其粘贴到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS），重启 Claude Desktop，marketbasketanalysis 服务器就会出现在工具列表中，包含全部 19 个工具。

零安装：托管端点

同一个服务器也以托管形式运行于 https://mcp.marketbasketanalysis.com/mcp（MCP streamable HTTP）。无需安装任何东西；将你的密钥作为 bearer 头发送，而不是环境变量：

claude mcp add --transport http marketbasketanalysis \
  https://mcp.marketbasketanalysis.com/mcp \
  --header "Authorization: Bearer mba_live_YOUR_KEY_HERE"

适用于任何支持远程连接的 MCP 客户端（Claude Code、Cursor、Smithery、自定义代理）。可选头：X-MBA-Base 可重新指向另一个由 MBA 运营的数据平面（例如 https://bigcommerce.marketbasketanalysis.com）；X-MBA-Platform 与 MBA_PLATFORM 环境变量对应。按设计，自托管的 WooCommerce 和 Magento 商店无法从托管端点访问；请使用上面的 npx 安装，并将 MBA_API_BASE 指向你自己的站点。

将服务器指向你的商店（MBA_API_BASE）

基础 URL 是每家商店各自的配置。默认情况下，服务器与共享托管后端 https://app.marketbasketanalysis.com 通信。如果你的数据位于其他地方——BigCommerce 商店、自托管后端或暂存实例——请设置 MBA_API_BASE，以便每个工具都能访问你自己的数据平面：

{
  "mcpServers": {
    "marketbasketanalysis": {
      "command": "npx",
      "args": ["-y", "@marketbasketanalysis/mcp"],
      "env": {
        "MBA_API_KEY": "mba_live_YOUR_KEY_HERE",
        "MBA_API_BASE": "https://your-store-backend.example.com"
      }
    }
  }
}

MBA_API_BASE 是重新指向整个服务器的唯一开关；全部 19 个工具都通过它路由。对于非本地主机，该值必须是 https:// URL（回环、私有、链路本地和元数据服务主机将被拒绝）。若要针对 localhost 上的后端进行本地开发，请设置 ALLOW_LOCAL_API_BASE=1 以允许使用 http://localhost 作为基础 URL。环境变量更改在服务器启动时生效，因此编辑该值后请重启你的 MCP 主机。

各平台的 MBA_API_BASE

基础 URL 是每家商店各自的配置。Shopify、BigCommerce 和 OroCommerce 商店由共享托管后端提供服务，因此它们使用默认值。WooCommerce 和 Magento 在商店安装内部本地运行后端，因此请将服务器指向商店自己的域名：

平台覆盖范围

服务器会写入规范的 /api/v1/... 路径，并根据平台重写它们，因为 WooCommerce 和 Magento 在商店内部按照各自的 REST 约定运行后端（分别为 marketbasketanalysis/v1 和 V1/marketbasketanalysis）。

19 个工具中有 10 个可覆盖 WooCommerce 和 Magento：其中 6 个源自 /recommendations（get_recommendations、get_bundle_for_cart、score_cross_sell、analyze_basket、propose_subscription_bundle、score_return_risk），另外还有 find_substitutes、get_rationale、forecast_bundle 和 predict_reorder。

其余 9 个属于商家运营工具组：get_opportunities、triage_opportunity、get_weekly_plan、execute_weekly_plan_action、get_drift_alerts、get_forecast_alerts、explain_opportunity、explain_drift 和 mine_hui_itemsets。这些端点在自托管后端上并不存在。在自托管后端调用其中一个，会返回一个明确指出端点名称的清晰“此平台不可用”错误，而非不透明的 404，并且不会产生网络往返。

有关分步安装（各操作系统的配置文件位置、如何生成 API 密钥、故障排除）：

• Claude Desktop: dist/mcp/claude-desktop-setup.md

• Cursor: dist/mcp/cursor-setup.md

• Windsurf: dist/mcp/windsurf-setup.md

身份验证

服务器从你的 MCP 主机传入的环境中读取 MBA_API_KEY，并在每个请求中将其作为 Bearer 令牌发送。要获取密钥：

1. 打开 MarketBasketAnalysis 管理后台（Shopify 应用抽屉，或 BigCommerce / WooCommerce / Magento / OroCommerce 管理后台）。

2. 点击左侧导航中的“API 密钥”。

3. 点击“创建密钥”，为其命名，并复制 mba_live_ 值（该值只显示一次）。

密钥按商店独立、可撤销，并可在同一界面轮换。后端只存储 SHA-256 哈希，因此如果密钥泄露，请重新生成。

不同市场的身份验证模型各不相同；MCP 服务器对此做了抽象，但仍值得了解：

• Shopify、BigCommerce：Bearer mba_live_... 直接透传。这是常见路径。

• WooCommerce：Bearer 使用 Woo 生成的密钥，该密钥必须带有 customer_data 作用域才能使用 predict_reorder。

• Magento：工具通过 Magento REST 接口（/V1/marketbasketanalysis/* 和 /V1/mba/*）访问商店；部分路由在商店侧受管理员令牌 / ACL 作用域保护。

• OroCommerce：对于 /api/ 路由，商店位于平台 OAuth2 防火墙之后；MCP 服务器实际调用的是精简客户端所代理到的托管后端，因此 mba_live_ 密钥仍然适用。

工具目录

19 个工具，按四个 Basket AI agent 角色以及两个运营组编排。“市场” 一列说明哪些后端提供了工具所调用的路由，这与该服务器当前能够访问哪些后端并非一回事：请参阅上文“平台覆盖范围”。“全部五个”指 Shopify、BigCommerce、WooCommerce、Magento、OroCommerce。

发现

捆绑包

这些工具的一切都源自 /recommendations（服务器在客户端一侧编排捆绑/评分逻辑），因此它们不需要额外的后端路由，适用于所有环境。

洞察

同样源自 /recommendations，因此适用于所有环境。

补货与预测

商家运营

这些工具调用的是当前由 BigCommerce 提供的 Bearer /api/v1 路由。Shopify 通过其嵌入式管理视图提供机会、漂移和每周计划，而不是 /api/v1 路由，因此这些工具针对 BigCommerce 后端解析。唯一的例外是 /explain-opportunity，它现在已由 BigCommerce 和 Shopify 提供；/explain-drift 仍仅限 BigCommerce。在缺少这些路由的平台上，工具会显示干净的上游 404。

高级挖掘

每个工具的示例提示词

将以下任意一条粘贴到 Claude Desktop / Claude Code / Cursor 聊天窗口中（在完成服务器配置后）：

• get_recommendations: "使用 marketbasketanalysis 查找客户在购买健身背包（产品 8472918765）时还会一起购买什么。"

• find_substitutes: "DSLR 机身缺货。有什么好的替代品？"

• get_rationale: "为什么健身背包会推荐搭配水壶？"

• get_bundle_for_cart: "我的购物车里有相机机身、32GB SD 卡和三脚架。要凑成一套完整的套件，可能还缺什么？"

• propose_subscription_bundle: "为客户 9876 打造一个每月订阅套件。"

• score_cross_sell: "清洁套件是 DSLR 相机机身的一个好的交叉销售品吗？"

• score_return_risk: *"相机 + 镜头 * 三脚架 + 背包 的退货风险如何？"*

• analyze_basket: "我正在考虑把相机 + 镜头 + SD 卡 + 包捆绑在一起。根据实际客户数据，这是一个强捆绑包吗？"

• predict_reorder: "Acme Corp（客户 7654321）本周有什么需要补货的？"

• forecast_bundle: "预测 b-camera-kit 捆绑包未来 12 周的需求，并推荐采购数量。"

• get_weekly_plan: "我的每周计划里有什么？"

• execute_weekly_plan_action: "运行我每周计划中的操作 a-42，已确认。"

• get_opportunities: "给我看看排名前三的推荐机会。"

• explain_opportunity: "为什么机会 opp-17 是一个好的交叉销售？"

• triage_opportunity: "激活机会 opp-17，已确认。"

• get_drift_alerts: "我的规则中是否有发生漂移的？"

• explain_drift: "为什么漂移警报 alert-7 中的那对商品会发生漂移？"

• get_forecast_alerts: "哪些捆绑包有缺货风险？"

• mine_hui_itemsets: "从这份 90 天订单数据中挖掘前 20 个高效用项集。"（Plus / Enterprise 层级）

每个工具的说明文档位于 cookbook 中。

环境变量

开发

git clone https://github.com/48x-ai/marketbasketanalysis-mcp
cd marketbasketanalysis-mcp
npm install
npm run typecheck
npm test
npm run dev    # tsx-based local run
npm run build  # emit ./dist

添加新工具

每个工具都是 src/tools/ 下的一个独立模块。要添加一个工具：

1. 创建 src/tools/myNewTool.ts，导出 definition 和 handler。对于简单的 GET，可参照 src/tools/getRecommendations.ts 的结构；对于带确认门控的 POST，可参照 src/tools/triageOpportunity.ts 的结构。

2. 在 src/tools/index.ts 中注册它：导入该模块并将其添加到 allModules 数组。

3. 在 src/tools/myNewTool.test.ts 中添加测试，覆盖：缺少密钥的回复、正常路径，以及至少一条上游错误路径。参照 src/tools/findSubstitutes.test.ts。

4. 在以上表格和 dist/mcp/smithery.yaml 中为其编写文档。

分发产物

monorepo 根目录下的 dist/mcp/ 目录存放安装示例（Claude Desktop、Cursor、Windsurf）、Smithery YAML 以及 Anthropic 市场提交内容。完整布局请参阅 dist/mcp/README.md。

发布

在 package.json 中提升版本号（保持 server.json 和 src/index.ts 同步），合并到 main，然后打上 mcp-v$VERSION 标签并推送该标签。工作流依次运行类型检查、测试、构建、标签/版本匹配检查，然后使用 NPM_TOKEN 仓库密钥执行 npm publish --access public --provenance。还提供 workflow_dispatch 手动触发，用于紧急运行。

完整的运维检查清单（包括一次性 NPM_TOKEN 设置和无需 CI 的手动发布后备方案）位于 docs/RELEASE.md。

故障排查

如需更深入的诊断，请参阅 dist/mcp/ 下各 IDE 的设置文档。

许可证

UNLICENSED，专有。