Keepa MCP Server

A high-performance MCP (Model Context Protocol) server for the Keepa API, providing programmatic access to Amazon product data with advanced caching, rate limiting, and optimization features.

✨ Features

• 🚀 High Performance: Built-in caching with LRU eviction and intelligent request optimization
• ⚡ Rate Limiting: Smart token bucket algorithm that syncs with Keepa API responses
• 🔄 Request Optimization: Automatic deduplication, batching, and priority queueing
• 📊 Comprehensive Metrics: Real-time performance monitoring and statistics
• 🛡️ Error Handling: Robust error recovery with custom error classes
• 🔧 TypeScript: Full type safety with comprehensive type definitions
• 🧪 Tested: Extensive unit test coverage with Vitest
• 📈 Chart Generation: Generate price/rank history charts with security features
• 🔒 Security: Streaming image validation with size limits and timeout protection

Status

✅ Production Ready! The server is fully functional with enterprise-grade performance optimizations.

📦 Available on NPM: Install directly with npx keepa-mcp-server@latest - no setup required!

Quick Start

Option A: NPM Package (Recommended)

1. Configure Your MCP Client

Add this to your MCP configuration (Claude Desktop, Cursor, etc.):

{
  "mcpServers": {
    "keepa": {
      "command": "npx",
      "args": ["keepa-mcp-server@latest"],
      "env": {
        "KEEPA_API_KEY": "your-keepa-api-key-here"
      }
    }
  }
}

That's it! The package will be automatically downloaded and run when needed.

✨ Benefits of NPX approach:

• 🚀 Zero setup - No cloning or building required
• 🔄 Always updated - Automatically uses latest version
• 💾 No disk space - Package cached temporarily by npm
• 🛡️ Consistent - Same version across all environments

Alternative installation methods:

# Install globally
npm install -g keepa-mcp-server

# Run directly without installation
npx keepa-mcp-server@latest

# Use specific version
npx keepa-mcp-server@latest

Option B: Local Development Setup

1. Clone and Install

git clone <repository-url>
cd keepa-mcp-server
npm install

2. Build the Project

npm run build

3. Configure Your MCP Client

{
  "mcpServers": {
    "keepa": {
      "command": "node",
      "args": ["<full-path-to-repository>/dist/main.js"],
      "env": {
        "KEEPA_API_KEY": "your-keepa-api-key-here"
      }
    }
  }
}

Get Your Keepa API Key

1. Visit Keepa.com
2. Create an account or log in
3. Navigate to the API section in your account settings
4. Subscribe to a plan and obtain your API key

Available Tools

📦 Product Data

| Tool | Description | Token Cost | | --------------- | --------------------------------------------- | --------------- | | get_product | Retrieve product data by ASIN or product code | 1 per product* | | product_chart | NEW! Generate price/rank history charts | Free |

get_product Parameters:

• domain (required): Amazon locale (see Domain IDs below)
• asin: ASIN or comma-separated list (max 100)
• code: UPC/EAN/ISBN or comma-separated list
• history: Include price history (0/1)
• offers: Number of marketplace offers (costs extra)
• stats: Include statistics (costs extra)
• buybox: Include buybox data (costs +2 tokens)
• stock: Include stock information (costs +2 tokens)

Response Filtering Options (NEW):

• includeHistory (boolean): Include full historical CSV data (default: false)
• summarizeHistory (boolean): Include statistical summary of historical data (default: true)
• maxHistoryDays (number): Limit historical data to recent X days
• excludeFields (array): List of fields to exclude from response
• maxOffers (number): Maximum number of offers to return (recommended: 20)
• includeOfferStockHistory (boolean): Include stock history in offers (default: false for large requests)
• offersCompact (boolean): Return minimal offer data for display purposes (default: false)

Important Notes:

• Historical data (price/rank/rating history) can be very large. By default, the tool summarizes this data to prevent response truncation.
• Requesting many offers (e.g., 50) can cause response size issues. Smart filtering is automatically applied for large offer requests (>30 offers).

Usage Examples

Get product with summarized history (default):

get_product({
  domain: 1,
  asin: 'B078WZ6976',
});
// Returns product data with csvSummary instead of full csv arrays

Get product with full historical data:

get_product({
  domain: 1,
  asin: 'B078WZ6976',
  includeHistory: true,
});
// Returns complete historical data - may be very large!

Get product with limited history:

get_product({
  domain: 1,
  asin: 'B078WZ6976',
  includeHistory: true,
  maxHistoryDays: 30,
});
// Returns only last 30 days of historical data

Get product with many offers (smart filtering):

get_product({
  domain: 1,
  asin: 'B07CYVDSF4',
  offers: 50,
  'only-live-offers': 1,
});
// Automatically applies smart filtering:
// - Limits to 20 offers
// - Excludes stock history
// - Uses compact format

Get product with controlled offer data:

get_product({
  domain: 1,
  asin: 'B07CYVDSF4',
  offers: 30,
  maxOffers: 10,
  offersCompact: true,
});
// Returns only 10 offers in compact format

product_chart Parameters:

• asin (required): Product ASIN (10-character code)
• domain (required): Amazon locale (see Domain IDs below)
• salesrank: Include sales rank (0/1, default: 1)
• bb: Include Buy Box price (0/1, default: 1)
• fba: Include FBA price (0/1, default: 1)
• fbm: Include FBM price (0/1, default: 1)
• range: Time range in days (30-365, default: 180)
• width: Chart width in pixels (400-2000, default: 800)
• height: Chart height in pixels (300-1200, default: 600)

🔍 Search & Discovery

| Tool | Description | Token Cost | | ----------------- | ------------------------------------- | ------------------------ | | get_search | Search Amazon products | 10 per page | | get_category | Get category details and hierarchy | 1 + optional parent tree | | get_deals | Browse current deals and promotions | 5 per 150 deals | | get_bestsellers | Get best-selling products by category | 50 per list |

👤 Seller Information

| Tool | Description | Token Cost | | ------------ | ------------------------------------- | ------------ | | get_seller | Get seller statistics and information | 1 per seller |

🌍 Domain IDs

Specify the Amazon marketplace using these domain IDs:

| ID | Domain | Country | | --- | ------------- | -------------- | | 1 | amazon.com | United States | | 2 | amazon.co.uk | United Kingdom | | 3 | amazon.de | Germany | | 4 | amazon.fr | France | | 5 | amazon.co.jp | Japan | | 6 | amazon.ca | Canada | | 8 | amazon.it | Italy | | 9 | amazon.es | Spain | | 10 | amazon.in | India | | 11 | amazon.com.mx | Mexico | | 12 | amazon.com.br | Brazil |

⚡ Performance Features

Smart Caching

• LRU Eviction: Automatically removes least-recently-used items
• TTL Management: Different cache durations for different data types
  • Products: 10 minutes
  • Deals: 5 minutes (frequently changing)
  • Bestsellers: 30 minutes (stable data)
• Cache Warming: Pre-populate cache with common requests

Rate Limiting

• Token Bucket Algorithm: Prevents API rate limit violations
• Dynamic Sync: Updates token counts from API responses
• Burst Handling: Allows temporary bursts up to 2x the rate limit

Request Optimization

• Deduplication: Prevents identical concurrent requests
• Batching: Combines multiple product requests (up to 100 ASINs)
• Priority Queueing: Search requests get higher priority
• Adaptive Concurrency: Adjusts based on response times and error rates

📊 Monitoring

Use the get_metrics tool to monitor performance:

{
  "requests": {
    "total": 1000,
    "successful": 980,
    "failed": 20,
    "cached": 450,
    "rateLimited": 5
  },
  "cache": {
    "hits": 450,
    "misses": 550,
    "hitRatio": 0.45,
    "size": 234
  },
  "performance": {
    "averageResponseTime": 350,
    "errorRate": 0.02,
    "cacheHitRatio": 0.45
  }
}

🔧 Configuration

Environment Variables

| Variable | Description | Default | | ---------------- | ------------------ | ----------------------- | | KEEPA_API_KEY | Your Keepa API key | Required | | KEEPA_BASE_URL | API base URL | https://api.keepa.com |

MCP Configuration Examples

For NPM/NPX installation:

{
  "mcpServers": {
    "keepa": {
      "command": "npx",
      "args": ["keepa-mcp-server@latest"],
      "env": {
        "KEEPA_API_KEY": "your-keepa-api-key-here",
        "KEEPA_BASE_URL": "https://api.keepa.com"
      }
    }
  }
}

For global installation:

{
  "mcpServers": {
    "keepa": {
      "command": "keepa-mcp-server",
      "env": {
        "KEEPA_API_KEY": "your-keepa-api-key-here"
      }
    }
  }
}

Advanced Configuration

The server can be configured programmatically when used as a library:

import { KeepaMCPServer } from './src/server/index.js';

const server = new KeepaMCPServer({
  apiKey: 'your-api-key',
  cache: {
    ttl: 600000, // 10 minutes
    maxSize: 1000, // Max cache entries
    strategy: 'lru', // LRU eviction
  },
  rateLimit: {
    tokensPerMinute: 60,
    capacity: 120,
  },
  enableOptimization: true,
  enableMetrics: true,
});

🧪 Development

Available Scripts

npm run dev          # Development with file watching
npm run build        # Production build
npm run test         # Run unit tests
npm run test:watch   # Run tests in watch mode
npm run lint         # Run ESLint
npm run typecheck    # Run TypeScript checks

Project Structure

src/
├── api/             # API clients (base and enhanced)
├── cache/           # Caching implementations
├── errors/          # Custom error classes and validation
├── server/          # MCP server implementation
├── tools/           # Individual tool implementations
├── types/           # TypeScript type definitions
└── utils/           # Utilities (rate limiting, logging, etc.)
tests/
├── unit/            # Unit tests
└── fixtures/        # Test data and mocks
docs/
└── keepa_openapi.yaml  # Keepa API specification

Testing

The project uses Vitest for testing with comprehensive coverage:

npm test                    # Run all tests
npm run test:coverage      # Run with coverage report
npm run test:ui           # Run with UI interface

🔧 Development Tools

MCP Inspector

MCP Inspector is a visual debugging and testing tool for MCP servers that provides a web-based interface for interacting with your server. It's invaluable for testing tools, viewing server responses, and debugging issues during development.

Installation

You can use MCP Inspector via npx (no installation required):

npx @modelcontextprotocol/inspector

Or install it globally:

npm install -g @modelcontextprotocol/inspector

Basic Usage

The easiest way to test the Keepa MCP Server with MCP Inspector is using the provided configuration file:

mcp-inspector --config mcp-inspector-local.json --server default

This will:

• Start the MCP Inspector proxy server on port 6277
• Launch the web UI at http://localhost:6274
• Connect to the Keepa MCP Server using the configuration in mcp-inspector-local.json

Configuration File

The mcp-inspector-local.json file configures how MCP Inspector connects to your server:

{
  "mcpServers": {
    "default": {
      "command": "node",
      "args": ["/path/to/keepa-mcp-server/dist/bin/main.js"],
      "env": {
        "KEEPA_API_KEY": "your-keepa-api-key-here"
      }
    }
  }
}

You can create multiple server configurations in the same file and switch between them using the --server flag.

Advanced Features

Custom Ports

# Use custom ports for the client UI and proxy server
CLIENT_PORT=8080 SERVER_PORT=9000 mcp-inspector --config mcp-inspector-local.json --server default

Environment Variables

Pass additional environment variables to your server:

mcp-inspector -e DEBUG=true -e LOG_LEVEL=verbose --config mcp-inspector-local.json --server default

CLI Mode

For automated testing and scripting:

# List available tools
mcp-inspector --cli --config mcp-inspector-local.json --server default --method tools/list

# Call a specific tool
mcp-inspector --cli --config mcp-inspector-local.json --server default \
  --method tools/call \
  --tool-name product_chart \
  --tool-arg asin=B08N5WRWNW \
  --tool-arg domain=1

Progress Notifications

MCP Inspector supports progress notifications for long-running operations. Configure timeouts:

# Set custom timeouts (in milliseconds)
MCP_SERVER_REQUEST_TIMEOUT=30000 \
MCP_REQUEST_MAX_TOTAL_TIMEOUT=120000 \
mcp-inspector --config mcp-inspector-local.json --server default

Troubleshooting MCP Inspector

Server Not Starting

• Ensure the server path in mcp-inspector-local.json is correct
• Check that dist/bin/main.js exists (run npm run build first)
• Verify your API key is set correctly

Connection Issues

• Check the console output for error messages
• Ensure no other services are using ports 6274 or 6277
• Try using custom ports if conflicts exist

Tool Validation Errors

• Verify all required parameters are provided
• Check parameter types match the schema (numbers vs strings)
• Use the UI's schema viewer to see expected parameters

Debugging Tips

• Enable debug mode: DEBUG=* mcp-inspector --config mcp-inspector-local.json --server default
• Check the browser console for client-side errors
• Use the Network tab to inspect MCP protocol messages

📜 API Reference

For detailed API documentation, see:

• Complete API Documentation
• Keepa API Specification
• Configuration Guide
• Security Documentation
• Troubleshooting Guide
• Publishing Guide

🚨 Error Handling

The server provides comprehensive error handling with a standardized error response format:

Error Types

• ValidationError: Invalid input parameters
• APIKeyError: Authentication issues
• RateLimitError: Rate limit violations
• NetworkError: Connection problems
• TimeoutError: Request timeouts
• UnauthorizedError: Access denied

Standardized Error Response Format

All errors follow a consistent structure:

{
  "error": {
    "type": "ValidationError",
    "message": "Invalid ASIN format. Must be 10 characters.",
    "code": "VALIDATION_ERROR",
    "statusCode": 400,
    "timestamp": "2023-11-01T12:34:56.789Z",
    "details": {
      "field": "asin",
      "value": "invalid",
      "constraint": "Must be 10 alphanumeric characters"
    }
  }
}

Security Features

• Image Validation: Streaming validation with size limits (max 50MB)
• Timeout Protection: Configurable timeouts prevent hanging requests
• Memory Protection: Prevents memory exhaustion attacks
• Input Sanitization: URL parameters are sanitized to prevent injection attacks

📈 Token Management

The Keepa API uses a token bucket system:

• Base Costs: See tool descriptions above
• Additional Costs: Optional parameters may increase token usage
• Rate Limits: Varies by subscription plan
• Monitoring: Use get_metrics to track token consumption

📦 Publishing

The Keepa MCP Server can be published to NPM either locally for testing or to the public registry. See the Publishing Guide for detailed instructions on:

• Local publishing with Verdaccio
• Direct NPM publishing
• Automated publishing via GitHub Actions
• Version management best practices

Quick commands:

npm run publish:dry-run    # Test what will be published
npm run publish:local      # Publish to local registry (Verdaccio)
npm run publish:patch      # Publish patch release to NPM

🏆 Best Practices

Managing Response Size

The MCP protocol has a 1MB message size limit. Here are best practices to avoid hitting this limit:

For Historical Data

• Default behavior: Historical data is automatically summarized
• Small time ranges: Use maxHistoryDays to limit data (e.g., 30, 60, 90 days)
• Specific data only: Use excludeFields to remove unnecessary CSV arrays

For Marketplace Offers

• Reasonable limits: Request ≤20 offers for general use
• Large requests: System automatically applies smart filtering for >30 offers
• Display only: Use offersCompact=true for UI display (minimal data)
• Analysis needs: Use maxOffers to control the exact number returned
• Stock history: Exclude with includeOfferStockHistory=false (default for large requests)

Token Cost Optimization

• Offers cost: 6 tokens per 10 offers (e.g., 50 offers = 30 tokens)
• Use filters: only-live-offers=1 reduces data and costs
• Batch wisely: Balance between number of products and data per product

Example: Optimized Large Request

// Bad: May exceed 1MB limit
get_product({
  domain: 1,
  asin: 'B07CYVDSF4',
  offers: 50,
  history: 1,
  stats: 365,
});

// Good: Optimized for size
get_product({
  domain: 1,
  asin: 'B07CYVDSF4',
  offers: 50,
  maxOffers: 20,
  offersCompact: true,
  summarizeHistory: true,
  maxHistoryDays: 30,
});

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Run the test suite
5. Submit a pull request

📄 License

This project is provided as-is. Please refer to Keepa's terms of service for API usage guidelines.

🆘 Support

For issues and questions:

1. Check the troubleshooting guide
2. Review existing issues in the repository
3. Create a new issue with detailed information

Note: This server requires a valid Keepa API subscription. Token costs and rate limits depend on your subscription plan.