Sorftime MCP

面向 Codex、Claude Code 和其他 MCP 客户端的 Sorftime Enterprise API 取数服务。

Sorftime MCP 以 stdio 方式运行，把 Sorftime 的产品、类目、关键词、积分和 Request 使用数据封装成 AI Agent 可直接调用的工具。使用者只需要在 MCP 客户端中配置 SORFTIME_API_KEY，不需要编写接口请求代码，也不需要在项目中保存 Sorftime Account-SK。

目录

• 为什么使用

• 能力概览

• 安装前置条件

• Codex 安装

• Claude Code 安装

• 工具体系

• 调用示例

• 站点映射

• 返回结构

• 安全边界

Related MCP server: readonly-mcp-akamai

为什么使用

• Agent 原生：工具命名、参数结构和返回格式面向 AI Agent 调用设计。

• 小工具面：只公开 10 个 MCP 工具，降低 Agent 选错工具的概率。

• 覆盖安全取数：通过 sorftime_call 白名单路由覆盖 32 个安全 Sorftime 方法。

• 可发现 schema：Agent 可以先查询 sorftime_methods 和 sorftime_method_schema，再决定调用方式。

• 统一返回：所有真实 Sorftime 请求都返回相同 envelope，便于后续分析、审计和错误处理。

• 凭证隔离：Sorftime Account-SK 只放在 MCP 客户端环境变量中，不写入仓库。

能力概览

安装前置条件

使用前需要准备：

• Sorftime Account-SK

• uvx

• Node.js / npx，仅在使用 npm 安装方式时需要

检查本机是否已有 uvx：

uvx --version

检查本机是否已有 npx：

npx --version

npm 包当前是一个轻量启动器，会调用 uvx 运行 PyPI 上的 Python MCP 包。因此使用 npx -y sorftime-mcp 时，本机也必须已经安装 uvx。

Codex 安装

通过 PyPI

[mcp_servers.sorftime]
command = "uvx"
args = ["sorftime-mcp"]

[mcp_servers.sorftime.env]
SORFTIME_API_KEY = "你的 Sorftime Account-SK"

通过 npm

[mcp_servers.sorftime]
command = "npx"
args = ["-y", "sorftime-mcp"]

[mcp_servers.sorftime.env]
SORFTIME_API_KEY = "你的 Sorftime Account-SK"

通过 GitHub 源码

[mcp_servers.sorftime]
command = "uvx"
args = [
  "--from",
  "git+https://github.com/ccchenhuohuo/sorftime-mcp.git",
  "sorftime-mcp"
]

[mcp_servers.sorftime.env]
SORFTIME_API_KEY = "你的 Sorftime Account-SK"

Claude Code 安装

通过 PyPI

claude mcp add --scope user \
  -e SORFTIME_API_KEY="你的 Sorftime Account-SK" \
  sorftime -- uvx sorftime-mcp

通过 npm

claude mcp add --scope user \
  -e SORFTIME_API_KEY="你的 Sorftime Account-SK" \
  sorftime -- npx -y sorftime-mcp

通过 GitHub 源码

claude mcp add --scope user \
  -e SORFTIME_API_KEY="你的 Sorftime Account-SK" \
  sorftime -- uvx --from git+https://github.com/ccchenhuohuo/sorftime-mcp.git sorftime-mcp

工具体系

Sorftime MCP 使用三层工具结构：

常用查询优先使用快捷工具。低频查询通过 sorftime_call 调用，调用前先用 sorftime_methods 和 sorftime_method_schema 确认 method、参数和 request 消耗。

调用示例

查询产品详情

{
  "input": {
    "asin": "B0CVM8TXHP",
    "domain": 1,
    "trend": 1
  }
}

通过路由查询销量估算

{
  "input": {
    "method": "AsinSalesVolume",
    "domain": 1,
    "params": {
      "ASIN": "B0CVM8TXHP",
      "Page": 1
    }
  }
}

查看方法 schema

{
  "input": {
    "method": "ProductRequest"
  }
}

站点映射

所有工具默认使用 domain=1。

IN、AE、AU、BR、SA 不支持历史数据回填。

返回结构

所有真实 Sorftime 请求都返回统一结构：

{
  "endpoint": "ProductRequest",
  "domain": 1,
  "estimatedRequestCost": 1,
  "requestConsumed": 1,
  "requestLeft": 1200,
  "code": 0,
  "message": null,
  "data": {},
  "rawResponse": {}
}

Agent 应优先读取：

• code：Sorftime 返回码

• message：Sorftime 返回消息

• data：业务数据

• requestConsumed：本次实际消耗

• requestLeft：剩余 Request

安全边界

当前版本只开放安全取数接口，默认不开放：

• 收藏词新增、修改、删除等账户状态变更接口

• 关键词监控、榜单监控、跟卖库存监控、ASIN 订阅等订阅管理接口

• 消耗监控点数或订阅点数、但不属于通用取数的接口

Sorftime Account-SK 不应该写入 README、Issue、PR、聊天记录或代码仓库。只应放在 MCP 客户端配置的环境变量中。

审计日志

默认不向标准输出写日志，避免污染 MCP stdio 协议。需要审计记录时，通过环境变量写入本地 JSONL 文件：

SORFTIME_AUDIT_LOG_PATH=logs/sorftime-mcp-audit.jsonl

审计日志会记录 endpoint、domain、参数摘要、估算消耗、实际消耗、剩余 Request、耗时和 Sorftime 返回码。日志不会记录 Sorftime Account-SK。

项目链接

• GitHub：ccchenhuohuo/sorftime-mcp

• PyPI：sorftime-mcp

• npm：sorftime-mcp