🚀 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

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

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

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

⬆ Back to top

Made with ❤️ by [Your Organization]

CoinGecko

Integrations