Emilin24/MCPServer

MCP Cryptocurrency Market Data Server

A Python-based MCP (Model Context Protocol) server built with FastAPI, providing:

• Real-time cryptocurrency prices
• Historical OHLCV (candles)
• WebSocket live updates
• Async CCXT integration
• In-memory caching
• Structured error handling
• Comprehensive automated tests

Designed for reliability, modularity, and extensibility.

🚀 Features

• REST API for current and historical market data
• WebSocket endpoint for streaming updates
• Async CCXT client (ccxt.async_support)
• TTL Cache to reduce redundant exchange calls
• Custom exceptions + retry logic
• Test suite with mocked external calls
• Clear separation of concerns (client/cache/exceptions/schemas)

📁 Project Structure

mcp-python-server/
├── main.py
├── mcp/
│   ├── __init__.py
│   ├── client.py
│   ├── cache.py
│   ├── exceptions.py
│   └── schemas.py
├── tests/
│   ├── __init__.py
│   ├── conftest.py
│   ├── test_api.py
│   └── test_cache.py
├── requirements.txt
└── README.md

📦 Installation

python -m venv venv
venv\Scripts\activate       # Windows
# or
source venv/bin/activate    # Linux/Mac
pip install -r requirements.txt

⚙️ Configuration

Environment variable:

Example:

set CACHE_TTL=120       # Windows
export CACHE_TTL=120    # Linux/Mac

▶️ Running the Server

uvicorn main:app --reload

Access:

• Swagger → http://localhost:8000/docs
• ReDoc → http://localhost:8000/redoc

📡 REST API

Health Check

GET /health

Response

{"status": "ok"}

Current Price

GET /v1/price/current/{exchange}/{symbol}

Valid symbol formats:

• BTC/USDT
• BTC-USDT
• BTC_USDT

Example

/v1/price/current/binance/BTC/USDT

Response

{
  "exchange": "binance",
  "symbol": "BTC/USDT",
  "price": 96321.45,
  "timestamp": 1731694812000
}

Historical OHLCV

GET /v1/price/historical/{exchange}/{symbol}

Query params:

Response

{
  "exchange": "binance",
  "symbol": "BTC/USDT",
  "data": [
    {
      "timestamp": 1762873200000,
      "open": 104560.15,
      "high": 104560.15,
      "low": 103170.33,
      "close": 103455.99,
      "volume": 2215.12756
    }
  ]
}

🔄 WebSocket API

WS /ws

Subscribe

{
  "action": "subscribe",
  "exchange": "binance",
  "symbol": "BTC/USDT"
}

Update example

{
  "symbol": "BTC/USDT",
  "last": 96251.40,
  "timestamp": 1731694712000
}

🔌 WebSocket Usage Example

Use any WebSocket client (e.g., wscat):

wscat -c ws://localhost:8000/ws

Subscribe:

{
  "action": "subscribe",
  "exchange": "binance",
  "symbol": "BTC/USDT"
}

💱 Supported Exchanges

• Binance
• Coinbase
• Kraken
• Bitfinex
• Huobi
• OKX
• Bybit
• Gate.io
• KuCoin
• Bitget

🧪 Testing

pytest -q

All CCXT calls are mocked—tests run without internet access.

📘 Approach & Assumptions

• The server is designed with clear modular separation (client, caching, exceptions, schemas, API handlers).
• All exchange calls are async and routed through a dedicated CCXT client wrapper with retry logic.
• Tests mock CCXT responses to ensure fully offline, deterministic test execution.
• WebSocket streaming is simplified to a periodic polling model due to varied native WS support across exchanges.
• Error handling is standardized and exposed through custom MCP exceptions.

🧩 Technical Design Notes

• Fully async I/O with ccxt.async_support
• Retry logic with exponential backoff
• Symbol normalization to BASE/QUOTE
• In-memory TTL caching for performance
• Clean module boundaries
• Strong type hints + Pydantic validation