keepa-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

Related MCP server: amazon-mcp

Install Via Claude Desktop MCPB

The easiest Claude Desktop install path is the .mcpb bundle from GitHub Releases.

1. Download keepa-adapter-vX.Y.Z.mcpb from the latest release.

2. Open the .mcpb file with Claude Desktop.

3. Enter your Keepa API key when Claude asks for Keepa API Key.

4. Enable or restart the extension if Claude Desktop prompts you.

5. 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

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

Monitoring Tools

Market Intelligence Tools

Official Keepa API Tools

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

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:

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.mcpb exists.

• Confirm release/keepa-adapter.mcpb exists for stable website download links.

• Open the .mcpb file with Claude Desktop.

• Enter KEEPA_API_KEY in 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 .mcpb to the release.

Troubleshooting

• Claude Desktop does not show the tools: restart Claude Desktop, confirm the extension is enabled, and reinstall the .mcpb if 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 .mcpb install path when possible. For manual installs, confirm node --version is 18 or newer.

• Build output looks stale: run npm run build, then npm run mcpb:pack again.

• 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, keep command as node, 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