MCP Cryptocurrency Market Data Server
A Python-based MCP (Market Communication Platform) 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```text
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```bash
python -m venv venv
venv\Scripts\activate # Windows
or
source venv/bin/activate # Linux/Mac
pip install -r requirements.txt
## ⚙️ Configuration
Environment variable:
| Name | Description | Default |
| ----------- | --------------------- | ------- |
| `CACHE_TTL` | TTL for cache entries | 60 sec |
Example:```bash
set CACHE_TTL=120 # Windows
export CACHE_TTL=120 # Linux/Mac
▶️ Running the Server```bash
uvicorn main:app --reload
Access:
* Swagger → http://localhost:8000/docs
* ReDoc → http://localhost:8000/redoc
---
# 📡 REST API
## Health Check```
GET /health
Response```json
{"status": "ok"}
---
## Current Price```
GET /v1/price/current/{exchange}/{symbol}
Valid symbol formats:
BTC/USDTBTC-USDTBTC_USDT
Example```
/v1/price/current/binance/BTC/USDT
**Response**```json
{
"exchange": "binance",
"symbol": "BTC/USDT",
"price": 96321.45,
"timestamp": 1731694812000
}
Historical OHLCV```
GET /v1/price/historical/{exchange}/{symbol}
Query params:
| Name | Description | Default |
| -------- | -------------------------- | ------- |
| interval | Candle timeframe | 1h |
| limit | Number of candles | 100 |
| since | Start timestamp (optional) | None |
**Response**```json
{
"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```json
{
"action": "subscribe",
"exchange": "binance",
"symbol": "BTC/USDT"
}
Update example```json
{
"symbol": "BTC/USDT",
"last": 96251.40,
"timestamp": 1731694712000
}
---
## 🔌 WebSocket Usage Example
Use any WebSocket client (e.g., wscat):```bash
wscat -c ws://localhost:8000/ws
Subscribe:```json
{
"action": "subscribe",
"exchange": "binance",
"symbol": "BTC/USDT"
}
# 💱 Supported Exchanges
* Binance
* Coinbase
* Kraken
* Bitfinex
* Huobi
* OKX
* Bybit
* Gate.io
* KuCoin
* Bitget
---
# 🧪 Testing```bash
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
