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.