KDPTop API 与 AI 接入

KDPTop 把我们持续抓取的 Amazon Books / Kindle eBooks 类目树、Best Sellers / New Releases / Top 100 Free 榜单快照、单书排名历史和类目机会指标，开放为 REST API 和 MCP（Model Context Protocol） 端点。 程序、ChatGPT、Grok、Claude、Cursor 等都可以直接检索这些数据。

认证

在 开发者中心 创建 API Key（形如 kdp_xxx，只显示一次，请妥善保存）。调用时任选一种方式携带：

Authorization: Bearer kdp_your_key     # 推荐
X-API-Key: kdp_your_key
?key=kdp_your_key                       # 仅限无法设置请求头的客户端

?key= 方式仅用于无法自定义请求头的客户端（如部分 MCP 连接器），Key 会出现在 URL 中，请只在可信客户端使用，泄露后立即在开发者中心吊销。

配额与错误码

REST 与 MCP 共用账号的每日调用配额（每次请求 / 每次工具调用计 1 次），历史数据范围随套餐而定。

REST 端点

Base URL：https://kdptop.com/api/v1，全部为 GET，返回 JSON。交互式文档：/api/v1/docs

示例

# 中文检索类目
curl "https://kdptop.com/api/v1/categories/search?q=温馨推理&store=kindle" \
  -H "Authorization: Bearer kdp_your_key"

# 某类目的 Kindle Best Sellers 前 20
curl "https://kdptop.com/api/v1/lists/154606011/best?limit=20" \
  -H "Authorization: Bearer kdp_your_key"

# 评论中位数 < 200、价格 >= $3.99 的 Kindle 叶子类目机会榜
curl "https://kdptop.com/api/v1/opportunities?store=kindle&leaf_only=true&max_median_reviews=200&min_median_price=3.99" \
  -H "Authorization: Bearer kdp_your_key"

字段说明

• node_id：Amazon 类目节点 ID；store：books 纸质书 / kindle 电子书
• list_type：best Best Sellers、new New Releases、free Top 100 Free（仅 Kindle）
• opportunity_score：0–100，越高代表评论门槛越低、换榜越快、新书越容易进入
• median_reviews / median_price：榜单书籍评论数 / 价格（美元）中位数；top100_turnover：较前一天的换榜比例
• new_release_ratio：90 天内首次出现的新书占比；prev_rank：前一天快照中的排名

MCP 端点

地址 https://kdptop.com/api/mcp，实现 MCP Streamable HTTP（无状态、JSON 响应，协议版本 2025-06-18 / 2025-03-26 / 2024-11-05）。 initialize 与 tools/list 无需认证，tools/call 需要 API Key。全部工具只读：

接入 ChatGPT

方式一：自定义 GPT（GPT Actions）

1. ChatGPT → 探索 GPT → 创建 → 配置 → 新建操作（Create new action）。
2. 选择「从 URL 导入」，填入 https://kdptop.com/api/v1/openapi.json。
3. 身份验证选 API 密钥，类型 Bearer，粘贴你的 kdp_ Key。
4. 隐私政策 URL 填 https://kdptop.com/，在指令里写明「需要 Amazon KDP 数据时调用 KDPTop」。

你是 Amazon KDP 选品助手。回答选题、类目、竞品、定价问题时，先调用 KDPTop：
1. 用 searchCategories 定位类目（中文或英文关键词都可以）；
2. 用 getCategory 看指标和子类目，用 getList 看 Top 榜单书籍；
3. 找机会时调用 findOpportunities，按 opportunity_score、median_reviews 解释原因；
4. 引用数据时注明抓取时间 captured_at，并附上 Amazon 链接。

方式二：Connectors / Apps（MCP）

在 ChatGPT 设置 → 应用与连接器 → 高级设置开启开发者模式 → 创建连接器，MCP 服务器 URL 填：

https://kdptop.com/api/mcp?key=kdp_your_key

认证方式选「无认证」，Key 通过 URL 参数传递。我们实现了 ChatGPT 要求的 search / fetch 工具，可用于深度研究。

方式三：OpenAI Responses API

curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5",
    "input": "Kindle 上哪些推理小说子类目评论门槛最低？",
    "tools": [{
      "type": "mcp",
      "server_label": "kdpdata",
      "server_url": "https://kdptop.com/api/mcp",
      "headers": { "Authorization": "Bearer kdp_your_key" },
      "require_approval": "never"
    }]
  }'

接入 Grok（xAI）

xAI Responses API（远程 MCP）

curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.7",
    "input": "用 KDPTop 找出 Kindle 言情类目下机会分最高的 5 个细分类目",
    "tools": [{
      "type": "mcp",
      "server_label": "kdpdata",
      "server_description": "Amazon KDP bestseller lists, categories and niche metrics",
      "server_url": "https://kdptop.com/api/mcp",
      "authorization": "Bearer kdp_your_key"
    }]
  }'

authorization 的值会原样作为 Authorization 头发送，需要带上 Bearer 前缀。可用 allowed_tools 限定工具。

xAI Python SDK

from xai_sdk import Client
from xai_sdk.chat import user
from xai_sdk.tools import mcp

client = Client()  # 读取 XAI_API_KEY
chat = client.chat.create(
    model="grok-4.7",
    tools=[mcp(server_url="https://kdptop.com/api/mcp", server_label="kdpdata",
               authorization="Bearer kdp_your_key")],
)
chat.append(user("温馨推理类目最近 30 天有哪些新书冲进了 Best Sellers？"))
print(chat.sample().content)

Grok CLI

grok mcp add --transport http kdpdata https://kdptop.com/api/mcp --header "Authorization: Bearer kdp_your_key"

接入 Claude / Cursor / 其他 MCP 客户端

支持远程 MCP 的客户端直接添加服务器即可。Cursor（~/.cursor/mcp.json）/ Claude Code 等：

{
  "mcpServers": {
    "kdpdata": {
      "url": "https://kdptop.com/api/mcp",
      "headers": { "Authorization": "Bearer kdp_your_key" }
    }
  }
}

Claude Code 命令行：

claude mcp add --transport http kdpdata https://kdptop.com/api/mcp --header "Authorization: Bearer kdp_your_key"

只能填 URL 的客户端（如 Claude.ai 自定义连接器）使用 https://kdptop.com/api/mcp?key=kdp_your_key。

llms.txt

我们在 https://kdptop.com/llms.txt 提供面向大模型的站点说明（数据范围、端点、认证方式）， 可直接贴给 AI 作为上下文。