# Cryptocurrency MCP Server

Python-based Model Context Protocol server for real-time and historical cryptocurrency data from 100+ exchanges via CCXT.

## Features

- **4 MCP Tools**: Real-time tickers, historical OHLCV, market listings, order books
- **100+ Exchanges**: Binance, Coinbase, Kraken, and more via CCXT
- **Smart Caching**: TTL-based caching for performance
- **Error Handling**: Custom exception hierarchy
- **Full Tests**: Comprehensive pytest coverage

## Setup

```bash
cd crypto-mcp-server
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
```

## Usage

**Run Server:**
```bash
python -m crypto_mcp_server
```

**Run Tests:**
```bash
pip install -r requirements-dev.txt
pytest tests/ -v
```

## MCP Inspector (optional)

You can install the MCP inspector globally with npm and run it against the package. This is useful for inspecting the MCP endpoints and payloads.

```bash
npm install -g @modelcontextprotocol/inspector
mcp-inspector python -m crypto_mcp_server
```

## MCP Tools

### get_ticker
Get real-time price data.
```json
{"symbol": "BTC/USDT"}
```

### get_ohlcv
Get historical candlestick data.
```json
{"symbol": "BTC/USDT", "timeframe": "1d", "limit": 100}
```

### get_markets
List all available markets.
```json
{}
```

### get_order_book
Get order book depth.
```json
{"symbol": "BTC/USDT", "limit": 20}
```

## Configuration

Optional `.env` file:
```bash
CACHE_TTL=60
DEFAULT_EXCHANGE=binance
LOG_LEVEL=INFO
```

## Project Structure

```
crypto-mcp-server/
├── crypto_mcp_server/      # Core server
│   ├── server.py           # MCP implementation
│   ├── data_fetcher.py     # CCXT integration
│   ├── cache.py            # Caching layer
│   └── exceptions.py       # Error handling
├── tests/                  # Test suite
├── requirements.txt        # 3 dependencies
└── test_mcp_tools.py       # Integration test
```

## Dependencies

**Core (3):**
- mcp - MCP server framework
- ccxt - Exchange integration
- python-dotenv - Configuration

**Dev (2):**
- pytest - Testing
- pytest-asyncio - Async tests

## Implementation

- **Architecture**: Modular design with separated concerns
- **Async/Await**: Full async support
- **Caching**: In-memory TTL cache
- **Testing**: Unit + integration tests

## License

MIT