MCP Binance Futures

A Model Context Protocol (MCP) server that enables any compatible AI model to autonomously trade Binance USDT-margined perpetual futures. Includes a separate paper-trading strategy lab that requires no credentials.

Overview

This project provides two MCP servers:

Server	File	Credentials Required	Real Orders
Binance Futures	`server.py`	Yes	Yes
Strategy Lab	`strategy_lab_server.py`	No	No (paper only)

Binance Futures Server

The live trading server exposes tools for:

Market scanning — ranks top-volume USDT pairs by momentum, RSI, volume spikes, and funding rates
Position management — open LONG/SHORT with automatic stop-loss and take-profit
Risk controls — hardcoded safety limits (max loss per trade, per day, max leverage, max positions)
Autopilot — a single heartbeat tool the AI calls repeatedly to monitor, cut losses, take profits, and open new trades

Strategy Lab (Paper Only)

A zero-credential research environment that uses only public Binance Futures endpoints:

Multi-method analysis — momentum, mean-reversion, breakout, or adaptive (auto-selects)
Historical backtesting — replay with fees, slippage, and drawdown tracking
Persistent paper account — simulated wallet with realistic cost modeling
Market scanning — rank USDT perpetuals by signal strength

Safety Limits

The live server enforces these immutable constraints:

Max loss per trade:     $10
Max loss per day:       $50
Max simultaneous pos:   4
Max leverage:           20x
Max margin per trade:   $30
Usable balance:         80% of available

The autopilot also enforces:

Auto-cut at -25% ROE
Auto-profit at +50% ROE

Requirements

Python 3.11+
A Binance account with Futures enabled (for the live server)
API key and secret with Futures trading permissions

Installation

git clone https://github.com/cociugv/mcp-binance-futures.git
cd mcp-binance-futures
pip install -r requirements.txt

Configuration

Environment Variables

Copy the example environment file and fill in your credentials:

cp .env.example .env

Edit .env with your Binance API credentials:

BINANCE_API_KEY=your_api_key_here
BINANCE_API_SECRET=your_api_secret_here

Security: Never commit .env to version control. The .gitignore already excludes it.

For the Strategy Lab (no credentials needed)

The strategy lab uses only unauthenticated public endpoints. Optional environment variables:

STRATEGY_LAB_STATE_FILE=./strategy_lab_state.json
STRATEGY_LAB_STARTING_BALANCE=50

Running the Servers

Live Trading Server

# Load environment variables and start
# Linux/macOS:
export $(cat .env | xargs) && python server.py

# Windows PowerShell:
Get-Content .env | ForEach-Object { if ($_ -match '^([^#].+?)=(.*)$') { [System.Environment]::SetEnvironmentVariable($matches[1], $matches[2]) } }; python server.py

Strategy Lab (Paper Only)

python strategy_lab_server.py

Strategy Lab Runner (Standalone Loop)

# Single heartbeat
python strategy_lab_runner.py --once --target 100 --method adaptive

# Continuous loop every 5 minutes
python strategy_lab_runner.py --target 100 --method adaptive --every-seconds 300

MCP Integration

Registering with an AI Client

Add the server to your MCP client configuration. Example mcp.json:

{
  "mcpServers": {
    "binance-futures": {
      "command": "python",
      "args": ["path/to/server.py"],
      "env": {
        "BINANCE_API_KEY": "your_api_key_here",
        "BINANCE_API_SECRET": "your_api_secret_here",
        "PYTHONIOENCODING": "utf-8"
      }
    },
    "binance-strategy-lab": {
      "command": "python",
      "args": ["path/to/strategy_lab_server.py"],
      "env": {
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}

Any AI model that supports MCP can drive these tools — Claude, GPT, Gemini, or any local model with an MCP-compatible client.

Available Tools

Live Server (`server.py`)

Tool	Description
`futures_balance`	Account balance, margin usage, and safety limits
`futures_positions`	Active positions with PnL, ROE, liquidation price
`futures_scan`	Scan top pairs for momentum signals
`futures_long`	Open a LONG with automatic SL/TP
`futures_short`	Open a SHORT with automatic SL/TP
`futures_close`	Close a position at market
`futures_set_leverage`	Set leverage for a symbol
`futures_orders`	List open orders
`futures_cancel`	Cancel all orders for a symbol
`futures_price`	Current price and 24h stats
`futures_status`	Daily session status and safety state
`futures_autopilot`	Autonomous heartbeat: monitor, act, scan, instruct

Strategy Lab (`strategy_lab_server.py`)

Tool	Description
`lab_safety`	Execution limits and guarantees
`lab_methods`	Available analysis methods and cost model
`lab_scan`	Rank markets by signal strength
`lab_compare`	Compare all methods on one symbol
`lab_backtest`	Historical replay with fees and slippage
`lab_paper_tick`	One research + paper-trading heartbeat
`lab_paper_status`	Paper wallet and marked positions
`lab_paper_reset`	Reset the simulated ledger

Architecture

server.py                    Live trading MCP server (requires credentials)
strategy_lab_server.py       Paper-only MCP server (no credentials)
strategy_lab_app.py          Application logic shared by MCP and CLI
strategy_lab.py              Strategy engine + paper account primitives
binance_public.py            Unauthenticated market-data adapter
strategy_lab_runner.py       Standalone CLI loop for paper trading

Disclaimer

This software is provided for educational and research purposes. Trading cryptocurrency futures carries significant financial risk. Past performance (including backtests) does not guarantee future results. The authors are not responsible for any financial losses incurred through the use of this software. Use at your own risk.

License

MIT License — see LICENSE for details.

MCP Binance Futures