yogirajbshinde21/crypto-mcp-server

Cryptocurrency Market Data MCP Server

A production-ready Python MCP (Model Context Protocol) server for retrieving real-time and historical cryptocurrency market data from major exchanges using the CCXT library. Now with a modern Flask web interface!

Features

• Real-time Price Data: Get current prices, bid/ask spreads, and 24h statistics
• Historical OHLCV Data: Fetch candlestick data with customizable timeframes (1m to 1M)
• Multi-Exchange Support: Works with Binance, Coinbase, Kraken, Bybit, and OKX
• Order Book & Trades: Access current order books and recent trade history
• Market Information: Browse available trading pairs and exchange information
• Modern Web Interface: Beautiful Flask-based dashboard to visualize all data
• Intelligent Caching: Reduces API calls with TTL-based caching (30s for real-time, 5min for historical)
• Robust Error Handling: Network failure recovery, rate limit management, and graceful degradation
• Comprehensive Testing: 80%+ test coverage with unit and integration tests

Installation and Setup

Requirements

• Python 3.8 or higher
• pip package manager

Installation Steps

1. Create and activate virtual environment:

python -m venv venv
.\venv\Scripts\Activate.ps1

2. Install dependencies:

pip install -r requirements.txt

3. Install package in development mode:

pip install -e .

Usage

Option 1: Flask Web Interface (Recommended)

Run the Flask web application:

python app.py

Then open your browser and navigate to:

http://127.0.0.1:5000

Features Available in Web Interface:

• 📊 Quick price dashboard for major cryptocurrencies
• 🔍 Symbol lookup with detailed 24h statistics
• 📈 Historical candlestick data visualization
• 📖 Live order book with bid/ask spreads
• 💱 Recent trades stream with auto-refresh
• 🏪 Browse all available trading pairs
• 🔄 Switch between exchanges (Binance, Coinbase, Kraken, etc.)
• ⚡ Real-time updates with auto-refresh options

Option 2: MCP Server

Run the MCP server directly:

python -m src

Option 3: Demo Client

Run the command-line demo client:

python demo_client.py

Choose from:

1. Quick Price Check (5 major coins)
2. Full Feature Demo (all 8 tools)
3. Both

API Endpoints (Flask)

The Flask application provides RESTful API endpoints:

Query Parameters:

• exchange: Exchange name (default: binance)
• timeframe: Candle timeframe (for historical data)
• limit: Number of results to fetch

Example API Call:

curl "http://127.0.0.1:5000/api/price/BTC/USDT?exchange=binance"

Testing

Run all tests:

pytest

Run with coverage report:

pytest --cov=src --cov-report=html --cov-report=term

Run specific test file:

pytest tests/test_server.py -v

Test Coverage

The test suite includes:

• Unit Tests: Individual function testing with mocked dependencies
• Integration Tests: End-to-end flow testing
• Edge Cases: Invalid inputs, network failures, rate limits
• Coverage: 80%+ across all modules

Architecture Overview

Design Decisions

CCXT Library: Chosen for its comprehensive exchange support, unified API across 100+ exchanges, and robust error handling.

Flask Web Framework: Simple, lightweight framework perfect for building RESTful APIs and serving web interfaces. Easy to extend and maintain.

Caching Strategy:

• Real-time data (prices, trades): 5-30 second TTL to balance freshness with API limits
• Historical data: 5-minute TTL since historical data changes less frequently
• Market info: 5-minute TTL as available pairs change infrequently
• Implemented with simple in-memory cache using TTL-based expiration

Modern UI Design:

• Dark theme with gradient accents for reduced eye strain
• Responsive grid layout for all screen sizes
• Real-time updates with AJAX for seamless experience
• Color-coded buy/sell indicators for quick visual analysis

Project Structure

crypto_mcp_server/
├── app.py                   # Flask web application
├── demo_client.py           # Command-line demo client
├── setup.py                 # Package configuration
├── requirements.txt         # Python dependencies
├── README.md               # This file
├── .gitignore              # Git ignore patterns
├── src/
│   ├── __init__.py          # Package initialization
│   ├── __main__.py          # MCP server entry point
│   ├── server.py            # MCP server and tool definitions
│   ├── exchange_client.py   # CCXT wrapper and exchange logic
│   ├── cache.py             # Caching utilities
│   └── utils.py             # Helper functions and validation
├── templates/
│   └── index.html           # Flask web interface template
├── static/
│   ├── style.css            # CSS styling
│   └── script.js            # JavaScript for interactivity
└── tests/
    ├── __init__.py          # Test package initialization
    ├── conftest.py          # Pytest fixtures
    ├── test_server.py       # Server tool tests
    ├── test_exchange_client.py  # Exchange client tests
    ├── test_cache.py        # Caching tests
    └── test_utils.py        # Utility function tests

MCP Tools Reference

Assumptions and Limitations

Assumptions

• API Rate Limits: Caching strategy assumes standard exchange rate limits (1200 req/min for Binance)
• Network Reliability: Basic retry logic implemented; assumes generally stable network
• Data Freshness: 30-second cache for real-time data balances freshness with performance
• Spot Markets: Primarily focused on spot trading pairs (not futures/derivatives)

Limitations

• Exchange Coverage: Limited to 5 major exchanges (easily extensible)
• Authentication: No private API endpoints (only public market data)
• Rate Limiting: Basic rate limit handling; no sophisticated throttling
• Persistence: In-memory cache only; data lost on restart
• Concurrency: Single-threaded caching; may need locks for high concurrency

Supported Exchanges

• Binance (default)
• Coinbase
• Kraken
• Bybit
• OKX

Data Freshness Trade-offs

• Real-time prices cached for 30 seconds (balance between freshness and API limits)
• Historical data cached for 5 minutes (historical data rarely changes)
• Order book cached for 10 seconds (reflects rapid market changes)
• Recent trades cached for 5 seconds (most time-sensitive data)

Screenshots

The web interface features:

• Dark Modern Theme: Easy on the eyes with gradient accents
• Responsive Design: Works on desktop, tablet, and mobile
• Real-time Updates: Live price cards with auto-refresh
• Interactive Charts: Historical data visualization
• Order Book Visualization: Side-by-side bid/ask display
• Trade Stream: Color-coded buy/sell indicators
• Market Browser: Browse all available trading pairs

License

This project is provided as-is for educational and demonstration purposes.

Contributing

This is a demonstration project. For production use, consider:

• Adding authentication for private endpoints
• Implementing Redis for distributed caching
• Adding WebSocket support for real-time streaming
• Enhancing rate limit handling
• Adding more sophisticated charting with Chart.js or D3.js