https://github.com/tienan92it/binance-mcp
https://github.com/tienan92it/binance-mcp
Last synced: 5 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/tienan92it/binance-mcp
- Owner: tienan92it
- License: mit
- Created: 2025-03-28T11:01:41.000Z (6 months ago)
- Default Branch: master
- Last Pushed: 2025-04-15T11:05:23.000Z (6 months ago)
- Last Synced: 2025-04-23T22:44:30.843Z (5 months ago)
- Language: Python
- Size: 66.4 KB
- Stars: 4
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Binance MCP Server
A Model Context Protocol (MCP) server that exposes Binance cryptocurrency exchange data to Large Language Model (LLM) agents. This server allows LLMs to access real-time and historical market data from Binance through a standardized interface.
## Features
- **Live Price Data**: Get current prices for any trading pair on Binance
- **Order Book Access**: Retrieve order book snapshots showing buy/sell interest at different price levels
- **Historical Price Data**: Fetch OHLCV (Open, High, Low, Close, Volume) candlestick data for any timeframe
- **Real-time WebSocket Streams**: Subscribe to real-time trade, ticker, and order book updates via WebSockets
- **Comprehensive Market Data**: Access trades, 24hr statistics, aggregate trades, rolling window data, and more
- **Exchange Information**: Access trading rules, symbol information, and fee structures
- **Read-only Operation**: All data is fetched via Binance's public REST API (no API keys required)
- **MCP Standard Compliant**: Works with any MCP-compatible LLM client
## Requirements
- Python 3.8+
- `mcp` package with CLI tools (`mcp[cli]`)
- `requests` library for REST API
- `websockets` library for WebSocket streams
- `uvicorn` for serving (optional)
## Installation
1. Clone this repository:
```bash
git clone https://github.com/yourusername/binance_mcp_server.git
cd binance_mcp_server
```
2. Install dependencies:
```bash
pip install -r requirements.txt
```
## Usage
### Running the Server Directly
To run the server in standalone mode:
```bash
python run_server.py
```
This will start the MCP server, which will listen for connections via STDIO.
### Development Mode with MCP Inspector
For development and testing, use the MCP Inspector:
```bash
mcp dev run_server.py
```
This opens the MCP Inspector interface where you can test the server's tools interactively.
### Installing in Claude Desktop
To use this server with Claude Desktop:
1. Install the MCP CLI tools if you haven't already:
```bash
pip install "mcp[cli]"
```
2. Install the server in Claude Desktop:
```bash
mcp install run_server.py
```
3. You can now access Binance data directly within your Claude Desktop conversations.
### Example Client
An example client script is provided to demonstrate programmatic usage:
```bash
python example_client.py
```
This script connects to the server and retrieves various types of market data.
## Available Tools
### Connectivity and Basic Info
- **ping_binance()**: Test connectivity to the Binance API server
- Example: `ping_binance()`
- **get_server_time()**: Get the current server time from Binance
- Example: `get_server_time()`
### Market Data
- **get_price(symbol)**: Get the current price for a trading pair
- Example: `get_price(symbol="BTCUSDT")`
- **get_order_book(symbol, depth=10)**: Get the current order book
- Example: `get_order_book(symbol="ETHUSDT", depth=5)`
- **get_historical_prices(symbol, interval="1d", limit=100)**: Get historical OHLCV data
- Example: `get_historical_prices(symbol="BTCUSDT", interval="1h", limit=24)`
- Valid intervals: "1m", "3m", "5m", "15m", "30m", "1h", "2h", "4h", "6h", "8h", "12h", "1d", "3d", "1w", "1M"
- **get_ui_klines(symbol, interval="1d", limit=100)**: Get UI-optimized candlestick data
- Example: `get_ui_klines(symbol="BTCUSDT", interval="1h", limit=24)`
- **get_recent_trades(symbol, limit=20)**: Get the most recent trades for a symbol
- Example: `get_recent_trades(symbol="BTCUSDT", limit=50)`
- **get_historical_trades(symbol, limit=20, from_id=None)**: Get older trades for a symbol
- Example: `get_historical_trades(symbol="BTCUSDT", limit=100, from_id=12345)`
- **get_aggregate_trades(symbol, limit=20)**: Get compressed/aggregate trades
- Example: `get_aggregate_trades(symbol="ETHUSDT", limit=30)`
- **get_24hr_ticker(symbol)**: Get 24-hour price change statistics
- Example: `get_24hr_ticker(symbol="BNBUSDT")`
- **get_all_24hr_tickers()**: Get 24-hour statistics for all symbols
- Example: `get_all_24hr_tickers()`
- **get_trading_day_ticker(symbol, type="FULL")**: Get trading day price change statistics
- Example: `get_trading_day_ticker(symbol="BTCUSDT", type="FULL")`
- **get_all_trading_day_tickers(type="FULL")**: Get trading day statistics for all symbols
- Example: `get_all_trading_day_tickers(type="MINI")`
- **get_rolling_window_ticker(symbol, window_size="1d", type="FULL")**: Get rolling window price statistics
- Example: `get_rolling_window_ticker(symbol="BTCUSDT", window_size="4h")`
- **get_all_rolling_window_tickers(window_size="1d", type="FULL")**: Get rolling window stats for all symbols
- Example: `get_all_rolling_window_tickers(window_size="4h", type="MINI")`
- **get_average_price(symbol)**: Get current average price (5-minute weighted average)
- Example: `get_average_price(symbol="BTCUSDT")`
- **get_book_ticker(symbol)**: Get best bid/ask prices and quantities
- Example: `get_book_ticker(symbol="ETHBTC")`
- **get_all_book_tickers()**: Get best bid/ask for all symbols
- Example: `get_all_book_tickers()`
### Market Info
- **get_exchange_info()**: Get comprehensive exchange information including trading rules and symbol list
- **get_trading_fees()**: Get the default trading fee rates (note: for demonstration purposes, returns default public fees)
### WebSocket Streams
- **subscribe_to_trade_stream(symbol)**: Subscribe to real-time trade events
- Example: `subscribe_to_trade_stream(symbol="BTCUSDT")`
- **subscribe_to_kline_stream(symbol, interval="1m")**: Subscribe to candlestick/kline updates
- Example: `subscribe_to_kline_stream(symbol="BTCUSDT", interval="5m")`
- **subscribe_to_ticker_stream(symbol)**: Subscribe to 24hr ticker updates
- Example: `subscribe_to_ticker_stream(symbol="ETHUSDT")`
- **subscribe_to_book_ticker_stream(symbol)**: Subscribe to best bid/ask updates
- Example: `subscribe_to_book_ticker_stream(symbol="BNBUSDT")`
- **subscribe_to_depth_stream(symbol, levels=10)**: Subscribe to order book updates
- Example: `subscribe_to_depth_stream(symbol="BTCUSDT", levels=5)`
- **list_active_subscriptions()**: List all active WebSocket subscriptions
- Example: `list_active_subscriptions()`
- **get_latest_stream_data(stream_name)**: Get the latest data from a stream
- Example: `get_latest_stream_data(stream_name="btcusdt@trade")`
- **unsubscribe_from_stream(stream_name)**: Unsubscribe from a stream
- Example: `unsubscribe_from_stream(stream_name="btcusdt@kline_1m")`
- **cleanup_all_streams()**: Close all WebSocket connections and clean up resources
- Example: `cleanup_all_streams()`
## Project Structure
```
binance_mcp_server/
├── binance_api.py # Core REST API interaction module
├── binance_ws_api.py # WebSocket connection management
├── commands/ # MCP command definitions
│ ├── __init__.py
│ ├── market_data.py # Price/order book/historical data commands
│ ├── market_info.py # Exchange info and metadata commands
│ └── websocket_streams.py # WebSocket stream commands
└── server.py # Main MCP server setup and initialization
```
## Examples
### Basic Connectivity
```python
# Check if Binance API is reachable
is_connected = ping_binance()
# Get the current server time (milliseconds since epoch)
server_time = get_server_time()
```
### Getting Current Market Data
```python
# Get the current price of Bitcoin
btc_price = get_price(symbol="BTCUSDT")
# Get detailed 24-hour statistics
btc_stats = get_24hr_ticker(symbol="BTCUSDT")
print(f"BTC price change: {btc_stats['priceChangePercent']}%")
print(f"BTC 24h volume: {btc_stats['volume']} BTC")
# Get rolling window statistics (4-hour window)
btc_4h_stats = get_rolling_window_ticker(symbol="BTCUSDT", window_size="4h")
print(f"BTC 4h price change: {btc_4h_stats['priceChangePercent']}%")
```
### Working with WebSocket Streams
```python
# Subscribe to real-time trade updates
trade_sub = subscribe_to_trade_stream(symbol="BTCUSDT")
# After some time, get the latest trade data
latest_trade = get_latest_stream_data(stream_name="btcusdt@trade")
print(f"Latest trade price: {latest_trade['data']['p']}")
# Subscribe to candlestick updates for chart data
kline_sub = subscribe_to_kline_stream(symbol="ETHUSDT", interval="5m")
# Clean up when done
unsubscribe_from_stream(stream_name="btcusdt@trade")
unsubscribe_from_stream(stream_name="ethusdt@kline_5m")
```
## Implementation Status
For a detailed overview of the implemented and planned API endpoints, refer to the [API Implementation Status](instructions/api-implementation-status.md) document.
## Extending the Server
### Adding New Tools
To add new tools, create appropriate functions in the Binance API module and then register them as MCP tools in one of the command modules.
### Supporting Private API Endpoints
To support authenticated API calls:
1. Modify `binance_api.py` to include authentication
2. Create additional command modules for trading operations
3. Register the new commands in `server.py`
## Troubleshooting
- **Connection Issues**: Ensure the server is running before attempting to connect with a client
- **Rate Limiting**: Binance may rate-limit excessive API calls; consider implementing caching for high-traffic deployments
- **WebSocket Stability**: WebSocket connections may disconnect after 24 hours (Binance limit); the server will attempt to reconnect automatically
- **Data Format**: Different symbols or intervals may return data in slightly different formats
## License
This project is licensed under the MIT License - see the LICENSE file for details.
## Acknowledgments
- Binance for providing a comprehensive public API
- The MCP project for standardizing LLM tool interactions