keepa-adapter MCP server
Commit Sep 14, 2026Lets an AI client monitor Amazon products, track price and BSR trends, and analyze market intelligence using the Keepa API.
Also known as BWB03/keepa-adapter
- Stars
- 16
- Tools
- 33
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Sep 14, 2026
- License
- MIT
What is keepa-adapter MCP?
keepa-adapter lets an AI client monitor Amazon products, track price and BSR trends, and analyze market intelligence using the Keepa API. It exposes 33 tools, such as keepa_get_product, keepa_get_price_history, keepa_get_buy_box.
Summary generated from the project's README
About keepa-adapter MCP server
Amazon sellers and market researchers can monitor product performance and price trends directly through an AI client using this adapter. It connects to the Keepa API to provide deep market intelligence, covering 33 different tools that range from basic product data retrieval to complex sales history analysis. Users can track specific ASINs, analyze Best Sellers Rank (BSR) trends, and measure the impact of promotions like lightning deals or coupons.
The server runs locally and can be installed in Claude Desktop via a specialized bundle or through manual JSON configuration. It requires a Keepa API key to function and allows for customization of the default Amazon marketplace domain, such as com, uk, or de. To manage API usage, users can set a specific token refill rate per minute. The system also includes a local SQLite database to store snapshots, enabling the detection of critical changes like buy box ownership shifts or significant price fluctuations.
What you can do with it
- 1Monitor product price changesAsk the AI to track specific ASINs and notify you when price or rank history shows significant movement.
- 2Analyze sales and BSR trendsRequest a detailed analysis of monthly sales volume and BSR deterioration for a specific product.
- 3Evaluate promotion effectivenessMeasure how much a coupon or lightning deal actually improved a product's rank and price.
- 4Audit buy box competitionCheck which sellers are winning the buy box and view their average pricing and FBA status.
Written from the project's README. Every use case is checked against a quote from it.
keepa-adapter MCP tools 33
Detected from the READMEkeepa_get_productkeepa_get_price_historykeepa_get_buy_boxkeepa_get_variationskeepa_check_tokenskeepa_track_asinskeepa_take_snapshotkeepa_get_changeskeepa_analyze_bsr_trendkeepa_check_variationskeepa_get_sales_historykeepa_get_deals
Show all 33 toolsShow fewer tools
keepa_get_seller_statskeepa_get_best_sellerskeepa_get_categorykeepa_search_productskeepa_find_productskeepa_browse_dealskeepa_search_categorieskeepa_get_sellerskeepa_find_sellerskeepa_get_top_sellerskeepa_get_lightning_dealskeepa_get_graph_imagekeepa_add_api_trackingskeepa_remove_api_trackingkeepa_get_api_trackingskeepa_get_tracking_notificationskeepa_get_tracking_listskeepa_set_tracking_webhookkeepa_add_promokeepa_list_promoskeepa_analyze_promo_impact
Configuration
KEEPA_API_KEYKEEPA_DEFAULT_DOMAIN
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablebwb03/keepa-adapter is public and reachablegithub.com/bwb03/keepa-adapter ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-09-14github.com/bwb03/keepa-adapter ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model33 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubkeepa-adapter
MCP server + OpenClaw skill for Amazon intelligence via the Keepa API. 33 MCP tools cover every path in Keepa's current endpoint index, plus local snapshots, change detection, BSR analysis, and promotion measurement.
Setup
git clone https://github.com/your-org/keepa-adapter.git
cd keepa-adapter
npm install
cp .env.example .env
# Edit .env and add your Keepa API key
Install Via Claude Desktop MCPB
The easiest Claude Desktop install path is the .mcpb bundle from GitHub Releases.
- Download
keepa-adapter-vX.Y.Z.mcpbfrom the latest release. - Open the
.mcpbfile with Claude Desktop. - Enter your Keepa API key when Claude asks for
Keepa API Key. - Enable or restart the extension if Claude Desktop prompts you.
- Start a new Claude chat and confirm the Keepa tools are available.
The bundle passes your key to the local MCP server as KEEPA_API_KEY. Optional settings such as KEEPA_TOKENS_PER_MINUTE, KEEPA_DEFAULT_DOMAIN, and KEEPA_DB_PATH remain available for manual MCP installs.
The bundle uses sql.js, so it does not load native Node add-ons inside Claude Desktop. That avoids Node ABI rebuild issues and macOS Electron code-signing failures for SQLite.
Build A Local MCPB
npm install
npm run mcpb:validate
npm run mcpb:pack
The packaged bundle is written to:
release/keepa-adapter-v1.2.0.mcpb
release/keepa-adapter.mcpb
Use the stable filename for website download links:
https://github.com/BWB03/keepa-adapter/releases/latest/download/keepa-adapter.mcpb
Environment Variables
| Variable | Required | Default | Description |
|---|---|---|---|
KEEPA_API_KEY |
Yes | — | Your Keepa API key |
KEEPA_TOKENS_PER_MINUTE |
No | 5 |
Token refill rate for your Keepa plan |
KEEPA_DEFAULT_DOMAIN |
No | com |
Default Amazon marketplace (e.g. uk, de, jp, ca, au) |
KEEPA_DB_PATH |
No | ~/.keepa-adapter/keepa.db |
Path to SQLite database |
International Marketplaces
All tools support international Amazon marketplaces via the domain parameter. Set KEEPA_DEFAULT_DOMAIN in your .env to avoid passing it on every call:
# .env
KEEPA_DEFAULT_DOMAIN=uk # All tools now default to Amazon.co.uk
Supported domains: com (US), uk, de, fr, jp, ca, it, es, in, mx, br. Keepa only supports Brazil on a subset of endpoints; the adapter validates that restriction before sending a request.
You can still override per-call by passing domain explicitly to any tool.
Usage
As an MCP Server (Claude Desktop)
If you prefer manual JSON config instead of the .mcpb installer, add this server to Claude Desktop's MCP config (claude_desktop_config.json):
{
"mcpServers": {
"keepa-adapter": {
"command": "node",
"args": ["/path/to/keepa-adapter/dist/index.js"],
"env": {
"KEEPA_API_KEY": "your_key_here"
}
}
}
}
Or run in development mode:
npm run dev
Claude Code / Codex Setup
Claude Code, Codex, and other stdio MCP clients can use the same local server command after building from source:
{
"mcpServers": {
"keepa": {
"command": "node",
"args": ["/absolute/path/to/keepa-adapter/dist/index.js"],
"env": {
"KEEPA_API_KEY": "your_key_here"
}
}
}
}
For Codex CLI-style configs, use the equivalent command/args/env shape supported by your client:
[mcp_servers.keepa]
command = "node"
args = ["/absolute/path/to/keepa-adapter/dist/index.js"]
[mcp_servers.keepa.env]
KEEPA_API_KEY = "your_key_here"
As an OpenClaw Skill (for bots)
import { KeepaSkill } from "keepa-adapter";
const skill = new KeepaSkill({ apiKey: "your_key" });
// Fetch product data
const products = await skill.getProduct(["B0012ZQPKG"]);
// Get daily alerts for Telegram/Slack/etc.
const alerts = await skill.getAlerts();
const summary = await skill.getDailySummary();
Daily Collection (Scheduler)
Run a one-time collection of all tracked ASINs:
# Via npm
npm run collect
# Or directly
npx tsx src/scheduler/runner.ts
Schedule with cron for daily monitoring:
0 6 * * * cd /path/to/keepa-adapter && KEEPA_API_KEY=xxx npm run collect
Playbooks
- Amazon Monitoring Playbook - Operating workflow for turning Keepa price, BSR, buy box, sales, variation, and promo signals into actions.
MCP Tools Reference
Read Tools
| Tool | Description |
|---|---|
keepa_get_product |
Fetch current product data for 1-100 ASINs (title, brand, prices, BSR, rating, buy box, images, features, variations, monthly sales, offer counts, out-of-stock %, Subscribe & Save status) |
keepa_get_price_history |
Get price/rank/review time series history (includes list price, lightning deal, FBA/FBM prices, offer counts) |
keepa_get_buy_box |
Get buy box ownership, seller info, and offers |
keepa_get_variations |
Get variation family tree (parent/child relationships) |
keepa_check_tokens |
Check remaining API tokens and refresh rate |
Monitoring Tools
| Tool | Description |
|---|---|
keepa_track_asins |
Add ASINs to the adapter's local monitoring list |
keepa_take_snapshot |
Fetch + store snapshot, return changes vs previous |
keepa_get_changes |
Query detected changes by ASIN, severity, or date range |
keepa_analyze_bsr_trend |
Analyze BSR trend and flag deterioration |
keepa_check_variations |
Check for orphaned children, parent changes, attribute drift |
Market Intelligence Tools
| Tool | Description |
|---|---|
keepa_get_sales_history |
Get monthly sales volume time series (units sold over time) |
keepa_get_deals |
Get ASIN-specific coupon, promotion, and lightning-deal history from /product |
keepa_get_seller_stats |
Get product-level Buy Box win %, average price, and FBA status from /product; optional stats_days sets the stats window (default: 30 days) |
keepa_get_best_sellers |
Get the best seller ASIN list for a category |
keepa_get_category |
Look up category details (name, parent, children, product count) |
Official Keepa API Tools
| Tool | Keepa operation |
|---|---|
keepa_search_products |
Product Search (/search?type=product) |
keepa_find_products |
Product Finder (/query, POST) |
keepa_browse_deals |
Browsing Deals (/deal, POST) |
keepa_search_categories |
Category Search (/search?type=category) |
keepa_get_sellers |
Seller Information (/seller) |
keepa_find_sellers |
Seller Finder (/sellerquery, POST) |
keepa_get_top_sellers |
Most Rated Sellers (/topseller) |
keepa_get_lightning_deals |
Lightning Deals (/lightningdeal) |
keepa_get_graph_image |
Graph Image API (/graphimage) |
keepa_add_api_trackings |
Add Keepa-hosted trackings (/tracking?type=add) |
keepa_remove_api_tracking |
Remove one or all Keepa-hosted trackings |
keepa_get_api_trackings |
Get or list Keepa-hosted trackings |
keepa_get_tracking_notifications |
Retrieve tracking notifications; read-only by default |
keepa_get_tracking_lists |
List named tracking lists |
keepa_set_tracking_webhook |
Configure the Keepa notification webhook |
keepa_track_asins remains a lightweight local snapshot list. The keepa_*_api_tracking* tools use Keepa's hosted Tracking API and affect the Keepa account associated with the API key.
Promo Tools
| Tool | Description |
|---|---|
keepa_add_promo |
Register a promo event (coupon, Lightning Deal, etc.) |
keepa_list_promos |
List promo events for an ASIN |
keepa_analyze_promo_impact |
Measure rank/price lift before, during, and after a promo |
Example Prompts
Once connected via Claude Desktop, try:
- "Show me product data for ASIN B0012ZQPKG"
- "Track these ASINs: B0012ZQPKG, B001234567"
- "Take a snapshot of all tracked ASINs and show me what changed"
- "Analyze the BSR trend for B0012ZQPKG over the last 10 days"
- "Check if any of my tracked products lost the buy box"
- "Add a coupon promo for B0012ZQPKG starting today"
- "Show me sales history for B0012ZQPKG"
- "What deals or coupons are active for B0012ZQPKG?"
- "Show me buy box stats by seller for B0012ZQPKG"
- "What are the best sellers in category 3760911?"
- "Look up category 3760911"
- "How many API tokens do I have left?"
Price Format
All price fields (amazon_price, new_price, buy_box_price) are returned in dollars, not cents. The adapter converts from Keepa's raw cent values automatically.
snapshot.new_price → 35.99 (dollars, ready to display)
Do not divide by 100 — the conversion is already done. Keepa's API returns prices in cents (e.g. 3599), but the adapter handles that internally.
Change Detection Severity
When snapshots are compared, changes are classified:
| Severity | Triggers |
|---|---|
| Critical | Title changed, buy box seller changed, parent ASIN lost/changed (orphaned) |
| Warning | Images changed, BSR worsened >20%, Amazon price changed >10%, rating dropped, monthly sales dropped >30%, new offer count went to 0, out-of-stock % increased ≥10 points |
| Info | Review count changed, features changed, description changed, new offer count changed >50%, Subscribe & Save status changed |
Development
npm run build # Build with tsup
npm test # Run unit tests
npm run mcpb:validate # Validate MCPB bundle
npm run mcpb:pack # Build release/keepa-adapter-vX.Y.Z.mcpb
npm run test:watch # Watch mode
npm run test:integration # Integration tests (requires KEEPA_API_KEY)
npm run discover # Hit live API and save raw response for schema modeling
npm run export:asins -- --input exports/todd-hydrapak-asins.txt
Raw ASIN Export
For one-off catalog dumps, put ASINs in a text file and run:
KEEPA_API_KEY=xxx npm run export:asins -- --input exports/todd-hydrapak-asins.txt
The exporter writes a timestamped exports/keepa-raw-* folder with raw Keepa JSON plus CSVs for product fields, decoded price/rank histories, variations, and offers. By default it skips the higher-token offer scrape; add --buybox --offers 20 when seller/offer detail is needed.
MCPB Release Flow
Version tags create GitHub Releases with the packaged .mcpb attached:
git tag v1.2.0
git push origin v1.2.0
The release workflow runs tests, builds the adapter, validates the MCPB manifest, packs the bundle, and uploads release/*.mcpb as a release asset.
MCPB Test Checklist
- Run
npm test. - Run
npm run build. - Run
npm run mcpb:validate. - Run
npm run mcpb:pack. - Confirm
release/keepa-adapter-v1.2.0.mcpbexists. - Confirm
release/keepa-adapter.mcpbexists for stable website download links. - Open the
.mcpbfile with Claude Desktop. - Enter
KEEPA_API_KEYin the install form. - Confirm Keepa tools appear in Claude Desktop.
- Run a low-cost call such as
keepa_check_tokens. - Temporarily install with a missing or invalid key and confirm the adapter returns a clear API-key error rather than crashing.
- Push a version tag and confirm the GitHub Action attaches the
.mcpbto the release.
Troubleshooting
- Claude Desktop does not show the tools: restart Claude Desktop, confirm the extension is enabled, and reinstall the
.mcpbif needed. - Missing API key errors: reinstall or edit the extension configuration and enter a valid Keepa API key.
- Invalid Keepa key or token errors: verify the key works against Keepa directly and has enough token budget.
- Node/runtime errors: use the
.mcpbinstall path when possible. For manual installs, confirmnode --versionis18or newer. - Build output looks stale: run
npm run build, thennpm run mcpb:packagain. - Network/API failures: confirm the machine running Claude Desktop can reach
https://api.keepa.com. - Manual JSON config does not work: use an absolute path to
dist/index.js, keepcommandasnode, and restart the MCP client after editing config.
Token Budget
Keepa charges tokens per API call. At 5 tokens/min (default plan):
- 7,200 tokens/day — 100 ASINs daily is comfortable
- Batch up to 100 ASINs per call for efficiency
- Token cost is surfaced in every response so Claude/bots can plan ahead
- The rate limiter self-adjusts from API response headers
Upgrade your Keepa plan for faster sweeps and on-demand history pulls.
License
MIT
keepa-adapter MCP questions
What tools does keepa-adapter MCP provide?
It exposes 33 tools, including keepa_get_product, keepa_get_price_history, keepa_get_buy_box, keepa_get_variations, keepa_check_tokens.
How do I install this on Claude Desktop?
The easiest way is to download the .mcpb bundle from the GitHub Releases page and open it with Claude Desktop.
Does the server support international Amazon marketplaces?
Yes, all tools support international marketplaces like UK, DE, JP, CA, and more via the domain parameter.