Binance

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

Clone this repository:

Install dependencies:

Usage

Running the Server Directly

To run the server in standalone mode:

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:

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:

Install the MCP CLI tools if you haven't already:

Install the server in Claude Desktop:

You can now access Binance data directly within your Claude Desktop conversations.

Example Client

An example client script is provided to demonstrate programmatic usage:

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

Examples

Basic Connectivity

Getting Current Market Data

Working with WebSocket Streams

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:

Modify `binance_api.py` to include authentication

Create additional command modules for trading operations

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