crypto_exchange_mcp

Crypto Exchange MCP Server

A comprehensive MCP (Model Context Protocol) server implementation for cryptocurrency exchanges, supporting Bybit, Binance, and OKX. This package provides a unified interface to interact with both public APIs (market data) and private APIs (trading, account management).

Features

Public APIs (No authentication required)

• Real-time price data - Get current ticker information
• Order book access - Retrieve order book depth for spot and futures markets
• Kline/candlestick data - Historical OHLCV data with various intervals
• Funding rate monitoring - Track perpetual contract funding rates
• Open interest tracking - Monitor contract open interest (Bybit)
• Trading pair information - Query available symbols

Private APIs (Authentication required)

• Account balance - Query wallet balances across multiple assets
• Position management - View open positions and unrealized PnL
• Order placement - Place market and limit orders
• Order cancellation - Cancel individual or all orders
• Order history - Retrieve past orders and fills
• Open orders - View pending orders

Supported Exchanges

Exchange	Spot	Futures	Public API	Private API
Bybit	✅	✅	✅	✅
Binance	✅	✅	✅	✅
OKX	✅	✅	✅	✅

Installation

From GitHub Release

uv tool install https://github.com/sydowma/crypto_exchange_mcp/releases/download/v0.3.1/crypto_exchange_mcp_python-0.3.1-py3-none-any.whl

With uv (Recommended)

cd crypto_exchange_mcp/crypto_exchange_mcp_python
uv sync

With pip

cd crypto_exchange_mcp/crypto_exchange_mcp_python
pip install -r requirements.txt

Configuration

For Public APIs Only

No configuration needed! Public market data endpoints work out of the box.

For Private APIs

Set environment variables with your API credentials:

# Bybit
export BYBIT_API_KEY="your_bybit_api_key"
export BYBIT_API_SECRET="your_bybit_api_secret"

# Binance
export BINANCE_API_KEY="your_binance_api_key"
export BINANCE_API_SECRET="your_binance_api_secret"

# OKX
export OKX_API_KEY="your_okx_api_key"
export OKX_API_SECRET="your_okx_api_secret"
export OKX_PASSPHRASE="your_okx_passphrase"

Or copy .env.example to .env and fill in your credentials:

cp .env.example .env

Usage with Claude Desktop

Unified Server (Recommended)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "crypto-exchange": {
      "command": "uv",
      "args": [
        "--directory",
        "{your_path}/crypto_exchange_mcp/crypto_exchange_mcp_python",
        "run",
        "crypto_exchange_server.py"
      ],
      "env": {
        "BYBIT_API_KEY": "your_bybit_api_key",
        "BYBIT_API_SECRET": "your_bybit_api_secret",
        "BINANCE_API_KEY": "your_binance_api_key",
        "BINANCE_API_SECRET": "your_binance_api_secret",
        "OKX_API_KEY": "your_okx_api_key",
        "OKX_API_SECRET": "your_okx_api_secret",
        "OKX_PASSPHRASE": "your_okx_passphrase"
      }
    }
  }
}

Individual Exchange Servers

You can also run each exchange separately:

{
  "mcpServers": {
    "bybit": {
      "command": "uv",
      "args": [
        "--directory",
        "{your_path}/crypto_exchange_mcp/crypto_exchange_mcp_python",
        "run",
        "bybit.py"
      ]
    },
    "binance": {
      "command": "uv",
      "args": [
        "--directory",
        "{your_path}/crypto_exchange_mcp/crypto_exchange_mcp_python",
        "run",
        "binance.py"
      ]
    },
    "okx": {
      "command": "uv",
      "args": [
        "--directory",
        "{your_path}/crypto_exchange_mcp/crypto_exchange_mcp_python",
        "run",
        "okx.py"
      ]
    }
  }
}

Available Tools

Public Market Data

• get_ticker(exchange, symbol) - Get price and 24h statistics
• get_orderbook(exchange, symbol, limit) - Get order book depth
• get_klines(exchange, symbol, interval, limit) - Get candlestick data
• get_symbols(exchange, spot, futures) - List trading pairs
• get_funding_rate(exchange, symbol) - Get perpetual funding rate
• get_open_interest(exchange, symbol) - Get contract open interest
• get_new_coins_okx(limit) - Get newly listed coins on OKX

Private Trading & Account

• get_balance(exchange) - Get account balances
• get_positions(exchange) - Get open positions
• place_order(exchange, symbol, side, order_type, quantity, price) - Place order
• cancel_order(exchange, symbol, order_id) - Cancel order
• get_open_orders(exchange, symbol) - Get pending orders
• get_order_history(exchange, symbol, limit) - Get order history

Utility

• get_supported_exchanges() - List exchanges and auth status
• get_external_mcp_servers() - List configured ready-made external MCP servers
• list_exchange_mcp_tools(exchange) - List tools from an external exchange MCP server
• call_exchange_mcp_tool(exchange, tool_name, arguments) - Call a tool exposed by an external exchange MCP server

External MCP Aggregation

The unified server can launch existing exchange MCP implementations as stdio child servers and expose them through one entrypoint.

Default external servers:

Exchange	External MCP	Default command
Bybit	Official Bybit Trading MCP	npx -y bybit-official-trading-server@latest
OKX	Official OKX Agent Trade Kit	npx -y @okx_ai/okx-trade-mcp@latest --modules market --read-only
Binance	Community Binance MCP Server	uvx --from binance-mcp-server binance-mcp-server

Use these tools from the main crypto-exchange MCP server:

1. get_external_mcp_servers() to inspect configured children.
2. list_exchange_mcp_tools("bybit") or another exchange to see child tools.
3. call_exchange_mcp_tool("bybit", "tool_name", {"arg": "value"}) to call a child tool.

Override or add child MCP servers with CRYPTO_EXCHANGE_MCP_CONFIG:

{
  "servers": {
    "okx": {
      "command": "npx",
      "args": [
        "-y",
        "@okx_ai/okx-trade-mcp@latest",
        "--modules",
        "market,spot,account",
        "--read-only"
      ],
      "env_keys": ["OKX_API_KEY", "OKX_API_SECRET", "OKX_PASSPHRASE"]
    }
  }
}

Set CRYPTO_EXCHANGE_MCP_ENABLE_DEFAULTS=false to disable built-in external MCP definitions and rely only on your config file.

Symbol Format by Exchange

Exchange	Spot Format	Futures Format
Bybit	BTCUSDT	BTCUSDT
Binance	BTCUSDT	BTCUSDT
OKX	BTC-USDT	BTC-USDT-SWAP

Note: OKX spot trading actually uses -USD suffix (e.g., BTC-USD), but -USDT also works for ticker queries.

Architecture

crypto_exchange_mcp_python/
├── core/                      # Core abstractions
│   ├── __init__.py
│   ├── base.py               # Base exchange class and data models
│   ├── config.py             # Configuration and credential management
│   └── exceptions.py         # Custom exceptions
├── exchanges/                 # Exchange implementations
│   ├── bybit/
│   │   └── client.py         # Bybit API client
│   ├── binance/
│   │   └── client.py         # Binance API client
│   └── okx/
│       └── client.py         # OKX API client
├── bybit.py                  # Legacy Bybit MCP server
├── okx.py                    # Legacy OKX MCP server
├── crypto_exchange_server.py # Unified MCP server
└── .env.example              # Example configuration

API Documentation

• Bybit API
• Binance API
• OKX API

License

Apache License 2.0