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.

Built with FastMCP and httpx.

---

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.