keepa-mcp

keepa-mcp

通过 Keepa API，为你的 AI 助手提供 Amazon 价格和销售排名历史记录。

---

非官方软件包。 keepa-mcp 与 Keepa GmbH 无关，未获得其认可，也未得到其支持。“Keepa”和“Amazon”是各自所有者的商标。这是一个独立的开源客户端，用于访问公开文档中描述的 Keepa API。

---

功能

工具	描述	提示词示例
get_product	标题、品牌、类别、当前价格、购物车、评论数和评分	“ASIN B08N5WRWNW 当前的 Amazon 价格和评分是多少？”
get_price_history	Amazon、新品、二手商品和购物车价格的解码时间序列	“显示 B08N5WRWNW 过去一年的价格历史记录”
get_sales_rank_history	随时间变化的销售排名以及需求趋势摘要	“B07PXGQC1Q 的需求趋势是在上升还是下降？”
search_products	按关键词搜索商品，返回匹配的 ASIN	“查找 Amazon 上‘wireless earbuds’对应的 ASIN”
get_best_sellers	Keepa 类别中的畅销 ASIN	“Electronics 类别中有哪些畅销商品？”
get_deals	按降价百分比和评分筛选当前降价优惠	“显示折扣至少为 30%、评分为 4.5 星的优惠”

---

快速开始

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "keepa": {
      "command": "npx",
      "args": ["-y", "keepa-mcp"],
      "env": {
        "KEEPA_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Claude Code

claude mcp add keepa -e KEEPA_API_KEY=your_key -- npx -y keepa-mcp

OpenAI Codex CLI

添加到 ~/.codex/config.toml：

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

[mcp_servers.keepa.env]
KEEPA_API_KEY = "YOUR_API_KEY_HERE"

---

获取 Keepa API 密钥

访问 https://keepa.com/#!api 注册并获取 API 密钥。

免费套餐每分钟提供 100 个令牌。 每次商品数据请求消耗的令牌数与检索的数据量成正比（历史记录长度、报价数量等）。通常，商品查询消耗 1-5 个令牌；畅销商品列表和优惠查询消耗更多。完整的令牌消耗表请参阅 Keepa API 文档。

令牌消耗一览：

• get_product：约 2-4 个令牌——商品记录，以及所需的 stats、rating 和 buybox 附加数据。没有这些数据，Keepa 不会返回当前价格、评分、评论数或报价数量。
• get_price_history / get_sales_rank_history：约 2-4 个令牌
• get_best_sellers：每次请求 50-100 个令牌
• get_deals：每页 5-25 个令牌
• 免费套餐每分钟补充 100 个令牌

不会请求实时报价数据（offers）。这会触发实时市场查询，每次额外消耗 10 个以上令牌；令牌池较小时，甚至可能导致请求直接失败。0.1.2 之前的版本始终发送 offers=20，因此 get_product 实际上从未只消耗此表之前所称的 1 个令牌。

如果达到配额上限，工具会返回清晰的错误消息；令牌池补充后即可重试。

---

对话示例

1. 商品调研

“查询 B08N5WRWNW，然后显示过去 6 个月的价格历史记录，并告诉我需求是否一直在增长。”

助手会调用 get_product，然后调用 get_price_history（range="6m"），再调用 get_sales_rank_history（range="6m"），最后综合给出判断。

2. 类别机会扫描

“获取 Electronics 类别（类别 172282）中排名前 20 的畅销商品，然后查询前三个商品的当前详情和销售排名趋势。”

助手会调用 get_best_sellers，然后针对排名前三的 ASIN 调用 get_product 和 get_sales_rank_history，并总结需求信号。

3. 寻找优惠

“查找评分高且折扣至少为 25% 的 Amazon 优惠，然后显示排名第一的商品的价格历史记录，确认降价是否属实。”

助手会调用 get_deals，参数为 min_price_drop_pct=25、min_rating=45，选出排名第一的 ASIN，然后调用 get_price_history（range="6m"），通过历史数据验证所称的降价。

---

开发

# Install dependencies
npm install

# Run tests (no live HTTP; all upstream calls are mocked)
npm test

# Build TypeScript to dist/
npm run build

# Start the server (requires KEEPA_API_KEY in environment)
KEEPA_API_KEY=your_key node dist/index.js

项目结构

src/
  index.ts                 # Server entry point, tool registration
  constants.ts             # API base URL, Keepa time offset, limits
  types.ts                 # TypeScript interfaces
  services/
    keepa-client.ts        # Fetch wrapper, time utilities, history decoder
  tools/
    get-product.ts
    get-price-history.ts
    get-sales-rank-history.ts
    search-products.ts
    get-best-sellers.ts
    get-deals.ts
tests/
  keepa-client.test.ts     # Unit tests for time conversion and history decoding
  tools.test.ts            # Integration tests with mocked fetch + fixture JSON
  fixtures/                # Realistic Keepa response shapes

---

构建者

由 Puya Ventures LLC 构建。我为产品研究、电商和 SaaS 团队构建定制 MCP 服务和 AI 集成。 欢迎联系：[email protected] | 作品集：puyarahmanian.com

属于 Product-Research MCP Suite： keepa-mcp · google-trends-mcp · junglescout-mcp

---

隐私

此服务完全在你的计算机上运行。它不会收集遥测数据，也不会存储任何数据。它唯一发出的网络请求是访问 Keepa API（api.keepa.com），并发送你的 API 密钥以及你查询的 ASIN、关键词或类别 ID。你的 API 密钥从 KEEPA_API_KEY 环境变量中读取，不会写入磁盘，也不会发送到 Keepa 以外的任何地方。请参阅 Keepa 的隐私政策：https://keepa.com/#!privacy

许可证

MIT。请参阅 LICENSE。