Chinmay48/crypto-mcp-server

🚀 Crypto MCP Server

Real-Time & Historical Cryptocurrency Data MCP Server (Python + FastMCP + CCXT)

This project is a Model Context Protocol (MCP) server that provides real-time and historical cryptocurrency market data to AI agents such as Claude Desktop, MCP CLI, or any MCP-compatible client.

The server is built using:

• FastMCP → easy MCP tool/plugin creation
• CCXT → reliable cryptocurrency market data from major exchanges
• Pydantic → strict data validation
• TTLCache → intelligent caching to reduce API load
• uv → fast Python runner
• pytest → unit tests

🧠 What Does This MCP Server Do?

This server exposes four MCP tools:

1. realtime_price

Fetches live crypto market price from any CCXT-supported exchange.

2. historical_data

Fetches OHLCV candle history (Open–High–Low–Close–Volume).

3. supported_markets

Lists all available trading pairs on an exchange.

4. health_check

Returns server health/status.

These tools allow Claude (or any MCP client) to perform real crypto market analysis live.

📸 Demo Screenshots

🏗️ Architecture Overview

main.py                     # MCP entrypoint
   |
   → src/server.py          # FastMCP server + tool definitions
           |
           ├── src/exchanges/ccxt_wrapper.py    # Crypto data fetch logic (CCXT)
           ├── src/schemas/market.py            # Pydantic response models
           └── tests/                           # Unit test suite (pytest)

🔄 Data Flow Diagram

Claude Desktop
      |
      |  (MCP Tool Call)
      v
FastMCP Server (server.py)
      |
      | calls
      v
CCXT Wrapper (ccxt_wrapper.py)
      |
      | fetches
      v
Exchange APIs (Binance, Kraken, Coinbase, etc.)
      |
      | returns data
      v
FastMCP → Claude Desktop → User Display

📁 Folder Structure

crypto-mcp-server/
│
├── main.py
│
├── src/
│   ├── server.py                  # MCP tool definitions
│   ├── exchanges/
│   │   └── ccxt_wrapper.py        # CCXT integration + caching
│   ├── schemas/
│   │   └── market.py              # Pydantic response models
│
├── tests/
│   ├── test_realtime.py           # realtime_price tests
│   ├── test_historical.py         # historical_data tests
│
├── requirements.txt
└── README.md

🚀 Technologies Used

⚙️ Installing & Running the MCP Server

1️⃣ Clone the Repository

git clone https://github.com/YOUR-USERNAME/crypto-mcp-server.git
cd crypto-mcp-server

2️⃣ Create Virtual Environment

python -m venv .venv

Activate it:

.venv\Scripts\activate

3️⃣ Install Dependencies

With uv:

uv sync

with pip:

pip install -r requirements.txt

4️⃣ Run the Server Manually (for debugging)

uv run main.py

Using the MCP Server with Claude Desktop

uv run mcp install main.py

🔍 MCP Tools (API) Documentation

Below are all available MCP tools exposed by the Crypto MCP Server and examples of how Claude interacts with them.

🟦 1. Realtime Price Tool

Tool name: realtime_price
Fetches the live market price of any crypto trading pair.

Arguments

Example Return

{
  "exchange": "binance",
  "symbol": "BTC/USDT",
  "price": 68000.2,
  "bid": 67995.1,
  "ask": 68005.4,
  "timestamp": 1731342335000
}

🟩 2. Historical OHLCV Tool

Tool name: historical_data
Fetches OHLCV candles (Open, High, Low, Close, Volume) for a trading pair.

Arguments

Example Prompt

Get 10 1h candles of BTC/USDT from Binance.

Return Format

Returned as a list of arrays: [timestamp, open, high, low, close, volume]

🟨 3. Supported Markets Tool

Tool name: supported_markets
Returns all tradable markets (symbols) available on a crypto exchange.

Example Prompt

List all supported markets for Binance.

Return Example

[
  "BTC/USDT",
  "ETH/USDT",
  "SOL/USDT",
  "XRP/USDT",
  
]