mcp/triplewhale

Triplewhale MCP Server 技术文档

1. 镜像概述和主要用途

Triplewhale MCP Server 是一个基于模型上下文协议（MCP）的服务器，旨在与 AI 应用（如 Anthropic Claude）集成，提供特定工具访问能力。其核心功能是通过 moby 工具帮助用户安全、便捷地访问电子商务性能数据。

什么是 MCP Server？

2. 核心功能和特性

2.1 基本特性

2.2 可用工具

3. 使用场景和适用范围

• 适用用户：电商商家、数据分析师、运营人员等需要获取店铺性能数据的角色。
• 核心场景：通过 AI 应用（如 Claude）查询店铺运营指标（如 ROAS、转化率等）、生成数据分析报告、获取可视化数据建议等。
• 使用条件：需提供有效的 shopId（店铺 ID）和 Triple Whale API 密钥。

4. 详细的使用方法和配置说明

4.1 Docker 运行命令

通过 Docker 运行 Triplewhale MCP Server 的基本命令如下：

bash
docker run -i --rm -e TRIPLEWHALE_API_KEY="your-triplewhale-api-key-here" mcp/triplewhale

参数说明：

• -i：以交互模式运行，允许输入输出
• --rm：容器退出后自动删除
• -e TRIPLEWHALE_API_KEY：设置环境变量，传入 Triple Whale API 密钥
• mcp/triplewhale：使用的 Docker 镜像名称

4.2 环境变量配置

4.3 MCP Server 集成配置示例

在支持 MCP 协议的 AI 应用中（如 Claude Desktop），配置 Triplewhale MCP Server 的示例如下：

json
{
  "mcpServers": {
    "triplewhale": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TRIPLEWHALE_API_KEY",
        "mcp/triplewhale"
      ],
      "env": {
        "TRIPLEWHALE_API_KEY": "your-triplewhale-api-key-here"  // 替换为实际 API 密钥
      }
    }
  }
}

5. 工具详情：moby

5.1 功能描述

moby 工具用于帮助用户访问电子商务性能数据。使用时需用户提供 shopId（店铺 ID）作为必需输入参数，工具将基于 shopId 和 API 密钥查询对应店铺的运营数据。

5.2 API 请求与响应 schema

基础信息

• API 标题：Triple Whale GPT API
• 描述：通过 Triple Whale Moby API 访问电商性能数据
• 版本：1.0.0
• 服务地址：https://api.triplewhale.com（生产环境）

请求路径

• 路径：/willy/moby-chat
• 方法：POST
• 操作 ID：answerMobyQuestion

请求参数（QuestionRequest）

响应结构（SimplifiedMobyResponse）

SimplifiedResponse 结构：

5.3 响应处理规则

1. 解析 responses 数组：按顺序处理每个响应项，若任一响应 isError: true，则整体视为错误。
2. 展示有效响应：
   • 显示用户的 question；
   • 以结构化格式（如表格）呈现 answer 数据；
   • 若 assistant 中包含可视化建议，提示“数据支持推荐的可视化格式”；
   • 若 assistant 中包含相似报告链接，提供链接地址；
   • 使用 assistantConclusion 询问用户是否需要进一步帮助。

5.4 错误处理规则

6. 为什么使用 Docker 运行 MCP Server 更安全？

Docker 为 MCP Server 提供了隔离的运行环境，有效限制服务器对主机系统的访问范围，降低数据泄露或***风险。同时，Docker 确保了环境一致性，避免因依赖差异导致的运行问题。

了解更多：为什么使用 Docker 运行 MCP Server 更安全

7. 许可证

本项目采用 MIT License 开源许可协议。详情参见 https://github.com/Triple-Whale/mcp-server-triplewhale%E3%80%82