船长 BI MCP 接入与使用指南

本指南旨在帮助用户通过 Model Context Protocol (MCP) 将船长 BI（CaptainBI）的各项功能集成到 AI Agent 中。由于该功能目前处于公测阶段，如遇问题，请反馈客服或技术支持人员。

一、生成 Client ID 与 Client Secret

在使用 MCP 连接船长 BI 之前，您需要获取 API 访问凭证。

操作步骤

· 1. 登录后台：使用主账号登录船长 BI，进入「授权」→「船长 API」。

· 2. 新增 API 授权：点击「新增 API 授权」按钮。若之前已创建过授权记录，也可直接复用已有授权。

· 3. 获取密钥：系统将生成以下两组凭证，请妥善保管，切勿泄露。

凭证说明：

· Client ID：系统生成的唯一标识，即 APPID。

· Client Secret：系统生成的访问密钥，即密钥。

二、配置 MCP

船长 BI MCP 采用标准协议，可适配多种支持 MCP 的 AI Agent。

1. 适配的 Agent

· WorkBuddy：原生支持 MCP 协议。

· ManusAI：原生支持 MCP 协议。

· Codex / Claude：通过配置文件支持。

· Cursor / VS Code (Cline)：通过插件集成。

· 其他：兼容 MCP 协议的开源框架。

2. 配置参数

您可以通过自然语言让 AI Agent 进行配置，参考以下 JSON 示例：

帮我配置 MCP：
{
  "mcpServers": {
    "captainbi": {
      "type": "streamable-http",
      "url": "https://mcp.captainbi.com/",
      "headers": {
        "x-client-id": "APPID",
        "x-client-secret": "密钥"
      }
    }
  }
}

请将 "APPID" 替换为您的 Client ID，将 "密钥" 替换为您的 Client Secret。

三、调用说明

配置成功后，AI Agent 将自动识别船长 BI 提供的工具集（Tools）。

1. 核心工具

· 店铺管理：获取店铺列表。

· 销量查询：按日期查询销量、额度及利润。

· 财务数据：查询店铺、商品财务相关指标。

· 广告分析：获取广告表现报告。

· 库存监控：查询 FBA 库存余量。

详细接口说明请查阅：

https://doc.captainbi.com/

2. 调用逻辑

· 自然语言交互：您可以直接对 Agent 说"查询我美国站昨天的销量"，Agent 会自动组合上述工具完成任务。

· 结果纠偏：如数据返回结果不对，可对 AI 重新说明数据逻辑后重新获取，并让 AI 记住取数习惯。

· 定时任务：可让 AI 制定定时任务，每日固定时间获取数据并形成报告。

四、注意事项

· 调用限制：API 调用次数限制，免费版每日仅可调用 100 次，超出之后会被提示限频。

· 安全性：Client Secret 相当于您的账号密码，请勿在公共代码库或不安全的 Agent 环境中明文存储。

· 权限范围：确保您的 API 账号拥有对应店铺的数据读取/写入权限。

· 写入限制：当前 MCP 暂不支持写入操作。

五、常见问题（FAQ）

Q：为什么连接提示 401 Unauthorized？

请检查 Client ID 或 Client Secret 是否填写正确，或检查该密钥是否已在后台被禁用。

Q：找不到某个站点的销量数据？

请确认该站点是否已在船长 BI 后台完成授权，并检查 OpenChannelId 是否匹配。

当前为 Beta 阶段，如遇问题，请联系技术人员协助处理，共同完善。