SergioDeIscarValera/coingeko-mcp-server

CoinGecko MCP Server 🚀

A comprehensive Model Context Protocol (MCP) server that provides cryptocurrency market data and interactive UI components through the CoinGecko API. This project demonstrates advanced MCP development with graphical interfaces following OpenAI SDK standards.

🌟 Features

📊 Core Tools

• Price Data: Real-time cryptocurrency prices and 24h changes
• Historical Charts: Historical price data with customizable time ranges
• Market Rankings: Top cryptocurrencies by market capitalization
• Trending Analysis: Currently trending cryptocurrencies
• Global Statistics: Overall market metrics and statistics
• Coin Search: Search functionality for finding specific cryptocurrencies
• Detailed Analysis: Comprehensive coin information and metrics
• Exchange Rates: Current exchange rates for various currencies
• Coin Comparison: Side-by-side comparison of multiple cryptocurrencies

🎨 Interactive UI Components

• Market Overview: Complete market dashboard with key metrics
• Trending Carousel: Interactive carousel of trending cryptocurrencies
• Crypto Charts: Dynamic price charts with multiple timeframes
• Coin Comparison: Visual comparison tool for multiple cryptocurrencies
• Responsive Design: Mobile-friendly interface with dark/light theme support

🛠️ Technical Features

• Full MCP compliance with OpenAI SDK standards
• RESTful API with Express.js server
• React-based interactive widgets
• TypeScript for type safety
• Zod schema validation
• Built-in error handling and validation
• Vercel deployment ready

🚀 Quick Start

Prerequisites

• Node.js (v18 or higher)
• npm or yarn
• Internet connection for CoinGecko API access

Local Development

1. Clone the repository

   git clone https://github.com/SergioDeIscarValera/coingeko-mcp-server.git
   cd coingeko-mcp-server
   

2. Install dependencies

   npm install
   

3. Build the UI components

   npm run build:ui
   

4. Start the development server

   npm run dev
   

The server will be available at http://localhost:3000/mcp

Production Deployment

Vercel Deployment

npm install
npm run build:ui
npm run build
vercel --prod

Manual Build

npm run build
npm start

📡 API Endpoints

MCP Tools

UI Resources

🏗️ Architecture

Project Structure

coingeko-mcp-server/
├── src/
│   ├── core/
│   │   └── types.ts           # TypeScript interfaces
│   ├── services/
│   │   └── CoinGeckoService.ts # API service layer
│   ├── tools/                 # MCP tools implementation
│   │   ├── GetCryptoPriceTool.ts
│   │   ├── GetCryptoHistoricalChartTool.ts
│   │   ├── MarketOverviewTool.ts
│   │   └── ... (11 total tools)
│   ├── resources/             # UI resource providers
│   │   ├── CryptoDashboardResource.ts
│   │   ├── MarketOverviewResource.ts
│   │   └── ... (4 total resources)
│   ├── prompts/
│   │   └── CryptoPrompts.ts   # MCP prompts
│   ├── ui/                    # React frontend
│   │   ├── src/
│   │   │   ├── main.tsx       # App router
│   │   │   ├── MarketOverview.tsx
│   │   │   ├── TrendingCarousel.tsx
│   │   │   ├── CoinComparison.tsx
│   │   │   └── CryptoChart.tsx
│   │   └── package.json
│   └── server.ts              # Main MCP server
├── package.json
└── tsconfig.json

Technology Stack

• Backend: Node.js, Express.js, TypeScript
• Frontend: React 18, TypeScript, Vite
• Charts: Recharts
• Validation: Zod
• MCP: @modelcontextprotocol/sdk
• API: CoinGecko API v3
• Deployment: Vercel

🔧 Configuration

Environment Variables

PORT=3000  # Server port (optional, defaults to 3000)

CoinGecko API

This project uses the free tier of the CoinGecko API. No API key is required, but rate limits apply:

• 10-30 calls/minute for free tier
• Consider upgrading for production use

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow TypeScript best practices
• Maintain comprehensive type definitions
• Add tests for new features
• Follow the existing code style
• Update documentation as needed

📄 Scripts

🐛 Troubleshooting

Common Issues

Server won't start

• Ensure port 3000 is available
• Check Node.js version (v18+ required)
• Verify all dependencies are installed

UI components not loading

• Run npm run build:ui before starting the server
• Check browser console for errors
• Ensure React dependencies are installed

API errors

• Check internet connection
• Verify CoinGecko API is accessible
• Check rate limiting (free tier: 30 calls/min)

📚 API Documentation

Tool Response Format

All tools return responses in the following format:

{
  "content": [
    {
      "type": "text",
      "text": "AI-readable response"
    }
  ],
  "structuredContent": {
    // Structured data for UI components
  }
}

Widget Integration

Widgets automatically detect their component type based on:

• _meta.component field in tool output
• Data structure analysis
• Fallback to default chart component

🔐 Security

• Input validation using Zod schemas
• Type-safe API responses
• CSP headers for widget security
• No sensitive data storage
• Rate limiting awareness

📈 Performance

• Efficient data fetching with minimal API calls
• Responsive UI components
• Optimized build output
• Asset optimization with Vite
• CDN-ready static assets

📝 License

This project is licensed under the MIT License. See the file for details.

🙏 Acknowledgments

• CoinGecko for providing the cryptocurrency API
• OpenAI for the MCP SDK and standards
• Model Context Protocol community

🔗 Links

• Personal GitHub
• Personal LinkedIn
• CoinGecko API Documentation
• Model Context Protocol Specification
• OpenAI MCP SDK

Made with ❤️ for the MCP community