🚀 CoinGecko API Server MCP
Seamless cryptocurrency data access for AI systems and applications
Features • Quick Start • Installation • Configuration • API Reference • MCP Integration • Pro API • Troubleshooting • License
🌟 Overview
The CoinGecko API Server MCP is a powerful, production-ready Node.js solution that provides seamless access to cryptocurrency market data through an elegant RESTful API and MCP (Marketplace Component Program) interface. It bridges AI systems like Claude with real-time crypto data while handling all the complexities of API rate limits, fallbacks, and error handling.
✨ Key Features
- 🔄 Dual API Support: Seamlessly integrates with both CoinGecko Free and Pro APIs
- 🧠 AI Integration: Full implementation of the MCP protocol for AI assistants
- 🛡️ Intelligent Fallback: Automatically switches between APIs to prevent rate limiting
- ⚡ Optimized Performance: Efficient request handling and response caching
- 📊 Comprehensive Data: Access to all essential cryptocurrency metrics
- 🔌 Simple Interface: Intuitive RESTful endpoints and JSON-RPC methods
- 🚦 Robust Error Handling: Clear error messages with appropriate status codes
- 🧩 Easy Deployment: Minimal configuration with guided setup process
- 📘 Extensive Documentation: Clear usage instructions and examples
🚀 Quick Start
# Option 1: Install and run with npx
npx coingecko-api-server
# Option 2: Clone and install manually
git clone https://github.com/yourusername/coingecko-api-server.git
cd coingecko-api-server
npm install
npm run setup
npm start
📦 Installation
Option 1: Using npx (Recommended)
The quickest way to get started:
npx coingecko-api-server
This will:
- 📥 Download and install the server
- 🧰 Run an interactive setup wizard
- 🔑 Ask for your CoinGecko API key (optional)
- 🚀 Start the server automatically
Option 2: Manual Installation
For more control over the installation process:
# Clone the repository
git clone https://github.com/yourusername/coingecko-api-server.git
cd coingecko-api-server
# Install dependencies
npm install
# Run the setup script
npm run setup
# Start the server
npm start
⚙️ Configuration
The server is configured using environment variables in the .env file:
| Variable | Description | Default |
|---|---|---|
PORT | Server port | 3000 |
COINGECKO_API_KEY | CoinGecko Pro API key (optional) | - |
CACHE_DURATION | Cache duration in seconds | 60 |
LOG_LEVEL | Logging level (error, warn, info, debug) | info |
📚 API Reference
RESTful Endpoints
Basic Endpoints
GET /api/ping- Check API server status
Price Data
GET /api/simple/price- Get price data for specified coins- Query params:
ids,vs_currencies,include_market_cap,include_24hr_vol,include_24hr_change,include_last_updated_at,precision
- Query params:
Coin Data
GET /api/coins/markets- Get market data for coins- Query params:
vs_currency,ids,category,order,per_page,page,sparkline,price_change_percentage
- Query params:
Market Data
GET /api/global- Get global cryptocurrency dataGET /api/search/trending- Get trending coins
Examples
Get Bitcoin Price in USD:
curl "http://localhost:3000/api/simple/price?ids=bitcoin&vs_currencies=usd"
Response:
{
"bitcoin": {
"usd": 45678.12
}
}
Get Top 5 Cryptocurrencies by Market Cap:
curl "http://localhost:3000/api/coins/markets?vs_currency=usd&order=market_cap_desc&per_page=5&page=1"
🤖 AI Integration (MCP)
This server implements the Marketplace Component Program (MCP) protocol, enabling AI systems like Claude to access cryptocurrency data.
MCP Integration Points
- JSON-RPC Endpoint:
/rpc- Handles method calls from AI clients - Schema Definition:
/mcp/schema- Defines available tools and parameters
Available MCP Methods
ping- Check API statusgetPrice- Get price data for specified cryptocurrenciesgetSupportedVsCurrencies- Get list of supported currenciesgetCoinMarkets- Get market data for coinsgetGlobal- Get global cryptocurrency datagetTrending- Get trending coins
For detailed integration instructions, see MCP_INTEGRATION.md.
💎 Pro API Benefits
This server supports both the CoinGecko Pro API and the free API:
| Feature | Free API | Pro API |
|---|---|---|
| Rate Limit | ~30 calls/minute | ~500 calls/minute |
| API Throttling | Yes | No |
| Support | Community | Priority |
| Data Freshness | 10-30 minutes | 1-2 minutes |
| Price | Free | Subscription |
For more details about the Pro API setup, see USING_COINGECKO_PRO.md.
🔧 Troubleshooting
| Issue | Solution |
|---|---|
| Rate limiting errors | Consider upgrading to Pro API or adjust your request frequency |
| Connection refused | Ensure the server is running on the specified port |
| Authentication errors | Check your API key in the .env file |
| Missing data | Verify the parameters in your request |
🧪 Development
# Run in development mode with hot reload
npm run dev
# Run tests
npm test
# Build for production
npm run build
🔄 How It Works
The server acts as a middleware between your applications and the CoinGecko API:
- Request Routing: Handles incoming requests from RESTful and JSON-RPC clients
- API Selection: Chooses between Free and Pro APIs based on configuration
- Rate Limit Management: Implements intelligent request throttling
- Response Processing: Formats and returns data in a consistent structure
- Error Handling: Provides detailed error information for troubleshooting
📱 Use Cases
- AI-Powered Financial Advisors: Enable AI systems to access real-time crypto data
- Investment Dashboards: Build cryptocurrency dashboards with reliable data access
- Portfolio Trackers: Create applications to monitor crypto holdings
- Market Analysis Tools: Develop tools for technical and fundamental analysis
- Trading Bots: Power automated trading systems with market data
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
🙏 Acknowledgments
- CoinGecko for the comprehensive cryptocurrency data API
- Anthropic for Claude AI and the MCP program
- The open-source community for their invaluable contributions