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)

Account (signed)

Orders (signed)

Position Management (signed)

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.