mcp-binance-futures
MCP server for Binance USDT-M Futures trading. Exposes tools for market data, account state, order management, and position/margin control — designed to give an LLM everything it needs to monitor, place, and manage futures trades.
Tools
Market Data (public, no auth)
| Tool | Description |
|---|---|
ping | Test API connectivity |
get_ticker | Price, 24 h stats, mark price, funding rate for a symbol |
get_order_book | Top N bids/asks for a symbol |
get_recent_trades | Latest public trades |
get_klines | OHLCV candlestick data (1m → 1w) |
get_symbol_info | Trading rules: tick size, lot size, min notional, order types |
Account (signed)
| Tool | Description |
|---|---|
get_balance | Wallet balances (non-zero assets only) |
get_positions | Open positions with PnL, leverage, margin type — optionally scoped to one symbol |
get_account_summary | Total balance, unrealized PnL, margin usage, open position count |
Orders (signed)
| Tool | Description |
|---|---|
place_order | Place LIMIT, MARKET, STOP, STOP_MARKET, TAKE_PROFIT, TAKE_PROFIT_MARKET, TRAILING_STOP_MARKET |
modify_order | Change price or quantity of an open LIMIT order |
cancel_order | Cancel a single order by ID |
cancel_all_orders | Cancel all open orders for a symbol |
get_open_orders | List all open orders for a symbol |
get_order | Get a specific order by ID |
get_order_history | Recent order history (all statuses) |
get_trade_history | Personal fill history for a symbol |
Position Management (signed)
| Tool | Description |
|---|---|
set_leverage | Set leverage multiplier (1–125×) for a symbol |
set_margin_type | Switch between ISOLATED and CROSSED margin |
adjust_isolated_margin | Add or remove margin from an isolated position |
set_position_mode | Switch between One-way and Hedge Mode |
get_position_mode | Get current position mode |
get_leverage_brackets | Leverage tiers with maintenance margin rates |
Setup
Requirements
- Python 3.11+
- uv (recommended) or pip
Install
# with uv (recommended)
uv sync
# or with pip
pip install -e .
API Keys
Create a Binance API key with Futures trading enabled. Set environment variables:
export BINANCE_API_KEY="your_api_key"
export BINANCE_API_SECRET="your_api_secret"
Security: Use IP whitelisting on your Binance API key. Never commit keys to version control.
Running
# stdio transport (default — for MCP clients like Claude Desktop)
python server.py
# or via the installed script
mcp-binance-futures
MCP Client Configuration
Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"binance-futures": {
"command": "python",
"args": ["/path/to/mcp-binance-futures/server.py"],
"env": {
"BINANCE_API_KEY": "your_api_key",
"BINANCE_API_SECRET": "your_api_secret"
}
}
}
}
With uv
{
"mcpServers": {
"binance-futures": {
"command": "uv",
"args": ["run", "--project", "/path/to/mcp-binance-futures", "mcp-binance-futures"],
"env": {
"BINANCE_API_KEY": "your_api_key",
"BINANCE_API_SECRET": "your_api_secret"
}
}
}
}
Testing
# install dev dependencies
uv sync --extra dev
# run all tests
pytest
# run with output
pytest -v
Tests use respx to mock all HTTP calls — no real API keys or network required.
Common Usage Patterns
Open a long position with stop loss and take profit
1. get_ticker(symbol="BTCUSDT") → check current price
2. get_balance() → check available margin
3. get_positions(symbol="BTCUSDT") → confirm no existing position
4. set_leverage(symbol="BTCUSDT", leverage=10)
5. set_margin_type(symbol="BTCUSDT", margin_type="ISOLATED")
6. place_order(symbol="BTCUSDT", side="BUY", order_type="MARKET", quantity=0.01)
7. place_order(symbol="BTCUSDT", side="SELL", order_type="STOP_MARKET",
stop_price=45000, close_position=True)
8. place_order(symbol="BTCUSDT", side="SELL", order_type="TAKE_PROFIT_MARKET",
stop_price=55000, close_position=True)
Modify a limit order
1. get_open_orders(symbol="BTCUSDT") → find the order ID
2. modify_order(symbol="BTCUSDT", order_id=123456, side="BUY",
quantity=0.01, price=48500)
Emergency close all
1. cancel_all_orders(symbol="BTCUSDT")
2. place_order(symbol="BTCUSDT", side="SELL", order_type="MARKET",
quantity=<position_size>, reduce_only=True)
Architecture
server.py — FastMCP server, all tool definitions
client.py — Async HTTP client: signing, transport, error handling
tests/
test_client.py — Unit tests for BinanceClient (signing, HTTP, errors)
test_server.py — Integration tests for all MCP tools
The client and server are intentionally kept in separate files: client.py handles all Binance API mechanics (HMAC signing, error parsing, HTTP verbs) while server.py contains only tool logic and MCP wiring. This makes both independently testable.