Content
# 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
```shell
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)
```shell
cd crypto_exchange_mcp/crypto_exchange_mcp_python
uv sync
```
### With pip
```shell
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:
```bash
# 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:
```shell
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):
```json
{
"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:
```json
{
"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`:
```json
{
"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](https://bybit-exchange.github.io/docs/v5/)
- [Binance API](https://binance-docs.github.io/apidocs/)
- [OKX API](https://www.okx.com/docs-v5/)
## License
Apache License 2.0
Connection Info
You Might Also Like
No recommendations available