{
  "markdown": "# keepa-mcp\n\n**Amazon price and sales-rank history for your AI assistant, via the Keepa API.**\n\n![CI](https://github.com/purahmanian/keepa-mcp/actions/workflows/ci.yml/badge.svg)\n![npm](https://img.shields.io/npm/v/keepa-mcp)\n\n---\n\n> **Unofficial package.** keepa-mcp is not affiliated with, endorsed by, or\n> supported by Keepa GmbH. \"Keepa\" and \"Amazon\" are trademarks of their\n> respective owners. This is an independent open-source client for the\n> publicly documented Keepa API.\n\n---\n\n## What it does\n\n| Tool | Description | Example prompt |\n|------|-------------|----------------|\n| `get_product` | Title, brand, category, current prices, buy box, review count and rating | \"What is the current Amazon price and rating for ASIN B08N5WRWNW?\" |\n| `get_price_history` | Decoded price time series for Amazon, new, used, and buy-box prices | \"Show me the price history for B08N5WRWNW over the past year\" |\n| `get_sales_rank_history` | Sales rank over time plus a demand trend summary | \"Is demand trending up or down for B07PXGQC1Q?\" |\n| `search_products` | Keyword product search, returns matching ASINs | \"Find ASINs for 'wireless earbuds' on Amazon\" |\n| `get_best_sellers` | Top ASINs in a Keepa category | \"What are the best sellers in Electronics?\" |\n| `get_deals` | Current price-drop deals filtered by drop % and rating | \"Show deals with at least 30% off and 4.5 stars\" |\n\n---\n\n## Quick start\n\n### Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json`\n(macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"keepa\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"keepa-mcp\"],\n      \"env\": {\n        \"KEEPA_API_KEY\": \"YOUR_API_KEY_HERE\"\n      }\n    }\n  }\n}\n```\n\n### Claude Code\n\n```bash\nclaude mcp add keepa -e KEEPA_API_KEY=your_key -- npx -y keepa-mcp\n```\n\n### OpenAI Codex CLI\n\nAdd to `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.keepa]\ncommand = \"npx\"\nargs = [\"-y\", \"keepa-mcp\"]\n\n[mcp_servers.keepa.env]\nKEEPA_API_KEY = \"YOUR_API_KEY_HERE\"\n```\n\n---\n\n## Getting a Keepa API key\n\n<!-- AFFILIATE -->\nSign up at [https://keepa.com/#!api](https://keepa.com/#!api) to get your API key.\n<!-- /AFFILIATE -->\n\nThe free tier provides **100 tokens per minute.** Each product data request\ncosts tokens proportional to the data retrieved (history length, number of\noffers, etc.). Typical product lookups cost 1-5 tokens; best-seller lists and\ndeals cost more. See the [Keepa API docs](https://keepa.com/#!discuss/t/api)\nfor the full token cost table.\n\n**Token economics at a glance:**\n\n- `get_product`: ~2-4 tokens — the product record plus the `stats`, `rating`\n  and `buybox` add-ons it needs. Keepa returns no current price, rating,\n  review count or offer count without them.\n- `get_price_history` / `get_sales_rank_history`: ~2-4 tokens\n- `get_best_sellers`: 50-100 tokens per request\n- `get_deals`: 5-25 tokens per page\n- Free tier refills at 100 tokens/minute\n\nLive offer data (`offers`) is *not* requested. It triggers a real-time\nmarketplace lookup costing 10+ extra tokens per call, which on a small bucket\ncan fail the request outright. Versions before 0.1.2 always sent `offers=20`,\nso `get_product` never actually cost the 1 token this table used to claim.\n\nIf you hit the quota, the tool returns a clear error message and you can\nretry after the bucket refills.\n\n---\n\n## Example conversations\n\n**1. Product research**\n\n> \"Look up B08N5WRWNW, then show me the last 6 months of price history and\n> tell me whether demand has been growing.\"\n\nThe assistant calls `get_product`, then `get_price_history` with range=\"6m\",\nthen `get_sales_rank_history` with range=\"6m\", and synthesises a verdict.\n\n**2. Category opportunity scan**\n\n> \"Pull the top 20 best sellers in Electronics (category 172282), then\n> get current details and sales rank trends for the first three.\"\n\nThe assistant calls `get_best_sellers`, then `get_product` and\n`get_sales_rank_history` for the first three ASINs, and summarises\nthe demand signals.\n\n**3. Deal hunting**\n\n> \"Find highly-rated Amazon deals with at least 25% off, then show\n> me the price history for the top result to confirm it is a genuine dip.\"\n\nThe assistant calls `get_deals` with min_price_drop_pct=25, min_rating=45,\npicks the top ASIN, then calls `get_price_history` with range=\"6m\" to\nvalidate the claimed price drop against historical data.\n\n---\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Run tests (no live HTTP; all upstream calls are mocked)\nnpm test\n\n# Build TypeScript to dist/\nnpm run build\n\n# Start the server (requires KEEPA_API_KEY in environment)\nKEEPA_API_KEY=your_key node dist/index.js\n```\n\n### Project structure\n\n```\nsrc/\n  index.ts                 # Server entry point, tool registration\n  constants.ts             # API base URL, Keepa time offset, limits\n  types.ts                 # TypeScript interfaces\n  services/\n    keepa-client.ts        # Fetch wrapper, time utilities, history decoder\n  tools/\n    get-product.ts\n    get-price-history.ts\n    get-sales-rank-history.ts\n    search-products.ts\n    get-best-sellers.ts\n    get-deals.ts\ntests/\n  keepa-client.test.ts     # Unit tests for time conversion and history decoding\n  tools.test.ts            # Integration tests with mocked fetch + fixture JSON\n  fixtures/                # Realistic Keepa response shapes\n```\n\n---\n\n## Built by\n\nBuilt by **Puya Ventures LLC**. I build custom MCP servers and AI integrations\nfor product-research, e-commerce, and SaaS teams. Get in touch:\n**purahmanian@gmail.com** | Portfolio: [puyarahmanian.com](https://puyarahmanian.com)\n\nPart of the **Product-Research MCP Suite**:\n[keepa-mcp](https://github.com/purahmanian/keepa-mcp) ·\n[google-trends-mcp](https://github.com/purahmanian/google-trends-mcp) ·\n[junglescout-mcp](https://github.com/purahmanian/junglescout-mcp)\n\n---\n\n## Privacy\n\nThis server runs entirely on your machine. It collects no telemetry and stores\nno data. The only network calls it makes are to the Keepa API\n(api.keepa.com), sending your API key and the ASINs, keywords, or category ids\nyou ask about. Your API key is read from the KEEPA_API_KEY environment variable\nand never written to disk or sent anywhere except Keepa. See Keepa's privacy\npolicy: https://keepa.com/#!privacy\n\n## License\n\nMIT. See [LICENSE](./LICENSE).\n",
  "bytes": 6308,
  "sha": "bd63a11f72cc4035281cbc76f216d2e55f307eb07f5425a34c885ec1faa0946a",
  "repo_slug": "purahmanian/keepa-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_purahmanian_keepa_mcp_f8aa6cfe/readme"
}