Provides tools for monitoring and trading Binance USDT-M Futures, including access to market data, account balances, position management, and order execution.
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 |
| Test API connectivity |
| Price, 24 h stats, mark price, funding rate for a symbol |
| Top N bids/asks for a symbol |
| Latest public trades |
| OHLCV candlestick data (1m → 1w) |
| Trading rules: tick size, lot size, min notional, order types |
Account (signed)
Tool | Description |
| Wallet balances (non-zero assets only) |
| Open positions with PnL, leverage, margin type — optionally scoped to one symbol |
| Total balance, unrealized PnL, margin usage, open position count |
Orders (signed)
Tool | Description |
| Place LIMIT, MARKET, STOP, STOP_MARKET, TAKE_PROFIT, TAKE_PROFIT_MARKET, TRAILING_STOP_MARKET |
| Change price or quantity of an open LIMIT order |
| Cancel a single order by ID |
| Cancel all open orders for a symbol |
| List all open orders for a symbol |
| Get a specific order by ID |
| Recent order history (all statuses) |
| Personal fill history for a symbol |
Position Management (signed)
Tool | Description |
| Set leverage multiplier (1–125×) for a symbol |
| Switch between |
| Add or remove margin from an isolated position |
| Switch between One-way and Hedge Mode |
| Get current position mode |
| 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-futuresMCP 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 -vTests 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 toolsThe 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.
Resources
Looking for Admin?
Admins can modify the Dockerfile, update the server description, and track usage metrics. If you are the server author, to access the admin panel.