🚀 CoinGecko API Server MCP

🌟 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:

1. 📥 Download and install the server
2. 🧰 Run an interactive setup wizard
3. 🔑 Ask for your CoinGecko API key (optional)
4. 🚀 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:

📚 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

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

Market Data

• GET /api/global - Get global cryptocurrency data
• GET /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

1. JSON-RPC Endpoint: /rpc - Handles method calls from AI clients
2. Schema Definition: /mcp/schema - Defines available tools and parameters

Available MCP Methods

• ping - Check API status
• getPrice - Get price data for specified cryptocurrencies
• getSupportedVsCurrencies - Get list of supported currencies
• getCoinMarkets - Get market data for coins
• getGlobal - Get global cryptocurrency data
• getTrending - 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:

For more details about the Pro API setup, see USING_COINGECKO_PRO.md.

🔧 Troubleshooting

🧪 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:

1. Request Routing: Handles incoming requests from RESTful and JSON-RPC clients
2. API Selection: Chooses between Free and Pro APIs based on configuration
3. Rate Limit Management: Implements intelligent request throttling
4. Response Processing: Formats and returns data in a consistent structure
5. 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