mikefossati/coinmarketcap-mcp-server

CoinMarketCap MCP Server

A comprehensive Model Context Protocol (MCP) server for real-time cryptocurrency analysis and market intelligence, powered by the CoinMarketCap Pro API. Fully compatible with free tier API keys.

🚀 Quick Start

Free Tier Setup (Recommended)

# 1. Clone and install
git clone <repository-url>
cd coinmarketcap-mcp-server
npm install

# 2. Configure for free tier
cp .env.example .env
# Edit .env with your free API key:
# CMC_API_KEY=your_free_api_key_here
# CMC_API_TIER=free

# 3. Build and test
npm run build
npm test

Claude Desktop Integration

{
  "mcpServers": {
    "coinmarketcap": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/path/to/coinmarketcap-mcp-server/dist/index.js"],
      "env": {
        "CMC_API_KEY": "your_api_key_here",
        "CMC_API_TIER": "free"
      }
    }
  }
}

📖 Need help with Claude Desktop setup? See the complete for step-by-step instructions, troubleshooting, and configuration examples.

🆓 Free Tier Support

NEW: Smart API tier configuration automatically disables premium-only tools for free tier users, preventing API errors.

✅ Free Tier Tools (7 available)

• get_crypto_price - Real-time cryptocurrency prices
• get_multiple_prices - Batch price queries
• get_top_cryptocurrencies - Top cryptocurrencies by market cap
• search_cryptocurrencies - Search cryptocurrencies
• get_market_overview - Global market overview
• get_market_dominance - BTC/ETH dominance analysis
• analyze_altcoin_season - Altcoin season detection

❌ Premium Tools (8 require paid plan)

• Raw technical data access
• Extended historical data
• Advanced market metrics
• Raw data for custom analysis

Check your status: Use the get_api_tier_status tool for detailed information.

🔧 Features

📊 Real-time Data

• Live cryptocurrency prices and market data
• Market capitalization and volume tracking
• Real-time market dominance metrics

📈 Raw Data Access (Paid tiers only)

• Raw Technical Data: OHLCV arrays for custom analysis
• Raw Price History: Unprocessed price and volume data
• Multi-asset Data: Raw comparison data for multiple cryptocurrencies

📋 Historical Data (Paid tiers only)

• Raw Historical OHLCV data without pre-calculated analysis
• Price History Arrays: Pure data for LLM analysis
• Multi-timeframe Data: Various time periods for comparison

⚡ Performance & Reliability

• Smart Tier Management: Automatic tool filtering based on API plan
• Intelligent Caching: Sub-second response times for frequent queries
• Rate Limiting: Built-in API rate limit management
• Error Prevention: No more "subscription plan doesn't support" errors
• Comprehensive Logging: HTTP status codes, response times, error details

📋 Available Tools

🆓 Free Tier Tools

💰 Premium Tools (Startup plan and higher)

🛠 Management Tools (Always available)

• get_server_info - Server capabilities and status
• get_cache_stats - Cache performance metrics
• get_rate_limit_status - API usage and rate limits
• get_api_tier_status - NEW: Current tier status and upgrade info

🐳 Docker Quick Start

1. Quick Setup

# Copy environment template
cp .env.example .env
# Edit .env and set your CMC_API_KEY

# Run with Docker
./docker-run.sh run

# Or use Docker Compose
./docker-run.sh compose

2. Docker Commands

# Basic usage
./docker-run.sh build          # Build image
./docker-run.sh run            # Run server
./docker-run.sh dev            # Development mode
./docker-run.sh logs           # View logs
./docker-run.sh stop           # Stop containers

# Advanced profiles
./docker-run.sh compose redis      # With Redis caching
./docker-run.sh compose monitoring # With Prometheus + Grafana
./docker-run.sh compose full       # Everything

3. Claude Desktop with Docker

{
  "mcpServers": {
    "coinmarketcap": {
      "command": "docker",
      "args": [
        "run", "--rm",
        "-e", "CMC_API_KEY=your_api_key_here",
        "-e", "CMC_API_TIER=free",
        "coinmarketcap-mcp"
      ]
    }
  }
}

📋 See for detailed Docker documentation

🔧 Configuration

API Tier Configuration

# .env file
CMC_API_KEY=your_api_key_here
CMC_API_TIER=free  # Options: free, startup, standard, professional, enterprise

# Optional: Optimize for your tier
CACHE_TTL_SECONDS=600          # Longer cache for free tier (saves API calls)
RATE_LIMIT_REQUESTS_PER_MINUTE=30  # Conservative for free tier

All Configuration Options

# CoinMarketCap API
CMC_API_KEY=your_api_key_here
CMC_BASE_URL=https://pro-api.coinmarketcap.com
CMC_API_TIER=free

# Server Configuration  
PORT=3000
NODE_ENV=production

# Performance Tuning
CACHE_TTL_SECONDS=300
CACHE_MAX_KEYS=1000
RATE_LIMIT_REQUESTS_PER_MINUTE=100

# Logging
LOG_LEVEL=info
DEBUG=coinmarketcap-mcp:*

🧪 Testing

# Basic functionality test
npm test

# Integration tests with real API
npm run test:integration

# Test with free tier restrictions
CMC_API_TIER=free npm run test:integration

Expected Results (Free Tier):

• ✅ 8/13 tests pass (basic features work)
• ❌ 5/13 tests blocked (premium features properly disabled)
• 🎯 No API errors (only tier restriction messages)

📊 Usage Examples

Free Tier Queries (Works with any API key)

# Claude Desktop queries that work on free tier:
"What's the current price of Bitcoin and Ethereum?"
"Show me the top 10 cryptocurrencies by market cap"  
"What's the current crypto market overview?"
"What's Bitcoin's market dominance today?"
"Are we in altcoin season based on current market data?"

Premium Tier Queries (Requires paid plan)

# Raw data access requiring paid API:
"Get raw technical data for Bitcoin"
"Show me Bitcoin's raw price history over the last 90 days"  
"Get raw historical data for Ethereum"
"Get raw market dominance data for analysis"
"Compare raw historical data for top 10 altcoins"

💡 Cost Optimization

Free Tier (10,000 calls/month)

• ✅ Use longer caching: CACHE_TTL_SECONDS=600
• ✅ Batch requests: get_multiple_prices vs multiple single calls
• ✅ Monitor usage: get_rate_limit_status tool
• ✅ Focus on price tracking and basic market analysis

Paid Tier

• 🚀 Shorter cache for fresh data: CACHE_TTL_SECONDS=300
• 🚀 Use all advanced features: Technical analysis, risk metrics, historical data
• 🚀 Higher rate limits: RATE_LIMIT_REQUESTS_PER_MINUTE=100+

🔍 Troubleshooting

Common Issues & Solutions

"Tool requires a paid CoinMarketCap API plan"

• ✅ Solution: Set CMC_API_TIER=free in .env to hide premium tools

Claude Desktop connection issues

• ✅ Solution: Use full node path in config: /opt/homebrew/bin/node
• ✅ Solution: Restart Claude Desktop after config changes

Rate limit exceeded

• ✅ Solution: Free tier: Increase cache TTL, space out requests
• ✅ Solution: Paid tier: Check if upgrade needed for higher limits

"Subscription plan doesn't support endpoint"

• ✅ Solution: Configure API tier properly to avoid these endpoints

📚 Documentation

• - Complete Claude Desktop integration guide
• - Complete guide to free vs paid tier setup
• - Monitoring, debugging, and performance analysis
• - Testing strategies and debugging
• - Production deployment with Docker and Kubernetes

🌟 Key Benefits

For Free Tier Users

• ✅ Zero API errors - Smart filtering prevents unsupported endpoint calls
• ✅ Clear guidance - Know exactly what's available vs what requires upgrade
• ✅ Reliable functionality - 7 core tools that work perfectly on free tier
• ✅ Cost effective - Get real value from 10,000 free monthly API calls

For Paid Tier Users

• 🚀 Full feature access - All 18 tools available including advanced analytics
• 🚀 Higher performance - Shorter cache times, higher rate limits
• 🚀 Advanced analysis - Technical indicators, risk metrics, historical data
• 🚀 Commercial usage - Licensed for business use

🛡 Production Ready

• ✅ Smart Error Handling - Graceful degradation and clear error messages
• ✅ Comprehensive Monitoring - Request tracing, performance metrics, cache stats
• ✅ Rate Limit Management - Built-in protection with usage monitoring
• ✅ Tier-aware Operation - Automatic feature enabling/disabling based on API plan
• ✅ Docker Support - Containerized deployment ready
• ✅ Extensive Testing - Integration tests for all scenarios

📈 Performance

• Cached Queries: <200ms response time
• Real-time Data: <500ms response time
• Complex Analysis: <2s response time
• Cache Hit Rate: >85% for frequent data
• API Efficiency: Smart caching reduces API calls by 60-80%

🎯 Perfect for both hobbyist crypto enthusiasts (free tier) and professional traders (paid tier). Get started in under 5 minutes with any CoinMarketCap API key.

License

MIT License - see file for details.