README.md
MCP server for Binance USDT-M Futures trading
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="BTCUSD
Tools (23)
pingTest API connectivityget_tickerPrice, 24 h stats, mark price, funding rate for a symbolget_order_bookTop N bids/asks for a symbolget_recent_tradesLatest public tradesget_klinesOHLCV candlestick data (1m → 1w)get_symbol_infoTrading rules: tick size, lot size, min notional, order typesget_balanceWallet balances (non-zero assets only)get_positionsOpen positions with PnL, leverage, margin typeget_account_summaryTotal balance, unrealized PnL, margin usage, open position countplace_orderPlace LIMIT, MARKET, STOP, STOP_MARKET, TAKE_PROFIT, TAKE_PROFIT_MARKET, TRAILING_STOP_MARKETmodify_orderChange price or quantity of an open LIMIT ordercancel_orderCancel a single order by IDcancel_all_ordersCancel all open orders for a symbolget_open_ordersList all open orders for a symbolget_orderGet a specific order by IDget_order_historyRecent order history (all statuses)get_trade_historyPersonal fill history for a symbolset_leverageSet leverage multiplier (1–125×) for a symbolset_margin_typeSwitch between ISOLATED and CROSSED marginadjust_isolated_marginAdd or remove margin from an isolated positionset_position_modeSwitch between One-way and Hedge Modeget_position_modeGet current position modeget_leverage_bracketsLeverage tiers with maintenance margin ratesEnvironment Variables
BINANCE_API_KEYrequiredYour Binance API keyBINANCE_API_SECRETrequiredYour Binance API secretConfiguration
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"}}}}Try it
→What is the current price and 24h funding rate for BTCUSDT?
→Check my current account balance and list all open positions.
→Place a market buy order for 0.01 BTCUSDT with a stop loss at 45000.
→Cancel all open orders for ETHUSDT.
→Set my leverage to 10x for the BTCUSDT pair.