abiesaga90/coingecko-mcp-server

🦎 CoinGecko MCP Server Setup

A comprehensive setup guide for running the CoinGecko MCP (Model Context Protocol) Server locally with Claude Desktop or any MCP-compatible AI client.

📋 Features

With the CoinGecko MCP Server, you can ask AI assistants to:

• 📊 Get real-time crypto prices for 15,000+ cryptocurrencies
• 📈 Market data & analytics including trading volumes, market caps
• 🔥 Trending coins & categories based on CoinGecko search data
• 🏛️ DeFi protocols and yield farming opportunities
• 🪙 Historical price data and OHLC charts
• 🔗 On-chain DEX data from GeckoTerminal (200+ networks)
• 📝 Token metadata including contracts, security info, descriptions
• 🎯 Portfolio analysis and performance tracking

🚀 Quick Start

1. Prerequisites

• Node.js 18+ (we'll install via nvm)
• CoinGecko API Key (Get Demo Key - 10,000 requests/month free)
• Claude Desktop or any MCP-compatible client

2. Setup Environment

# Install nvm (Node Version Manager)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# Reload your shell or run:
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

# Install Node.js LTS
nvm install --lts
nvm use --lts

3. Configure MCP Server

For Claude Desktop:

1. Copy the template:

   cp claude_desktop_config.template.json claude_desktop_config.json
   

2. Add your API key: Edit claude_desktop_config.json and replace YOUR_COINGECKO_API_KEY_HERE with your actual API key.

3. Install to Claude Desktop:

   # macOS
   mkdir -p ~/Library/Application\ Support/Claude
   cp claude_desktop_config.json ~/Library/Application\ Support/Claude/claude_desktop_config.json
   
   # Windows
   mkdir -p $APPDATA/Claude
   cp claude_desktop_config.json $APPDATA/Claude/claude_desktop_config.json
   

4. Restart Claude Desktop

4. Test Installation

# Test the MCP server
COINGECKO_DEMO_API_KEY="your_api_key_here" COINGECKO_ENVIRONMENT="demo" npx -y @coingecko/coingecko-mcp --list

💡 Example Queries

Once configured, ask Claude:

Basic Queries

• "What is the current price of Bitcoin?"
• "Show me the top 10 cryptocurrencies by market cap"
• "What are the trending coins today?"

Advanced Analysis

• "Compare the performance of Ethereum, Solana, and Cardano over the last 30 days"
• "Show me the top DeFi tokens and their 24h volume"
• "What are the best performing categories in crypto this week?"

Data-Driven Insights

• "Create a risk-return analysis of the top 15 DeFi tokens"
• "Show me the correlation between Bitcoin dominance and altcoin performance"
• "Analyze the liquidity trends in DEX protocols"

📊 Visualization Examples

The repository includes Python scripts for creating sophisticated crypto visualizations:

• DeFi Sector Analysis (defi_analysis.py) - 6-panel dashboard with performance metrics
• Crypto Visualizer (crypto_visualizer.py) - Interactive charts using Plotly
• Market Health Scoring - Custom algorithms for sector analysis

Running Visualizations

# Install Python dependencies
pip install matplotlib plotly pandas seaborn

# Run DeFi sector analysis
python3 defi_analysis.py

# Run crypto visualizer demo
python3 crypto_visualizer.py

🔧 Configuration Files

📈 API Limitations

Demo API (Free)

• ✅ 10,000 requests/month
• ✅ ~30 requests/minute
• ✅ Basic endpoints (prices, markets, trending)
• ✅ DEX data (GeckoTerminal integration)
• ❌ No premium endpoints (advanced analytics)

Pro API (Paid)

• ✅ Higher rate limits (plan-dependent)
• ✅ Premium endpoints (OHLC, supply charts)
• ✅ Enterprise features (webhooks, bulk data)

🎯 Optimized Prompting

To maximize your API quota:

High-Efficiency Queries (1-2 API calls)

"Get the current global crypto market overview with Bitcoin dominance"
"Show top 50 cryptocurrencies with biggest gains/losses today"
"List all DeFi categories with their total market caps"

Multi-Asset Analysis (3-5 API calls)

"Compare Bitcoin, Ethereum, BNB, Solana, and Cardano across all metrics"
"Analyze the top 10 DEX tokens with volume and liquidity data"
"Show trending vs top market cap coins side by side"

🛠️ Development

Project Structure

coingecko-mcp/
├── README.md                           # This file
├── .gitignore                          # Git ignore rules
├── claude_desktop_config.template.json # Claude Desktop config template
├── mcp_config.template.json           # General MCP config template
├── setup_environment.sh               # Environment setup script
├── test_coingecko_mcp.sh              # Testing script
├── crypto_visualizer.py               # Visualization toolkit
├── defi_analysis.py                   # DeFi sector analysis
└── examples/                          # Usage examples

Contributing

1. Fork the repository
2. Create a feature branch
3. Add your improvements
4. Test with your API key
5. Submit a pull request

🔒 Security

• ⚠️ Never commit your API keys to version control
• ✅ Use the template files and add your keys locally
• ✅ Add *_config.json to .gitignore (already included)
• ✅ Keep your Demo API key private and rotate regularly

📚 Resources

• CoinGecko API Documentation
• Model Context Protocol (MCP) Spec
• Claude Desktop Download
• CoinGecko MCP Server Package

🆘 Troubleshooting

Common Issues

"MCP server not loading"

# Check Node.js installation
node --version && npm --version

# Verify nvm is loaded
export NVM_DIR="$HOME/.nvm" && [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

"API key invalid"

# Test your API key
curl "https://api.coingecko.com/api/v3/ping?x_cg_demo_api_key=YOUR_KEY_HERE"

"Rate limit exceeded"

• Check your monthly quota in the CoinGecko Dashboard
• Use more efficient prompts (see Optimized Prompting section)

📄 License

MIT License - see file for details.

Made with ❤️ for the crypto community

Star ⭐ this repo if it helped you build better crypto AI tools!