binance-futures-mcp

Binance MCP Server

A Model Context Protocol (MCP) server that provides comprehensive access to Binance Futures API endpoints. This server implements all major trading, account management, and market data functionality as documented in the Binance Futures API.

📋 Table of Contents

🚀 Quick Start

Install the package:
pip install binance_futures_mcp
Run the server:
uvx binance_futures_mcp --binance-api-key "your_key" --binance-secret-key "your_secret"
Configure in your MCP client (see Configuration section for detailed setup)

✨ Features

11 essential trading tools across 2 categories (Account Information and Market Data)
Proper authentication handling (rejects unauthenticated requests)
Error handling and graceful degradation
Real-time market data access

📦 Installation

Option 1: PyPI Installation (Recommended)

Install the package from PyPI:

pip install binance_futures_mcp

Option 2: Docker Deployment

For containerized deployment:

# Clone the repository
git clone https://github.com/alexcandrabersiva/bin-mcp.git
cd binance-mcp-server

# Build the Docker image
docker build -t binance-mcp-server .

# Run with environment variables
docker run -e BINANCE_API_KEY="your_api_key" -e BINANCE_SECRET_KEY="your_secret_key" \
  binance-mcp-server --binance-api-key "$BINANCE_API_KEY" --binance-secret-key "$BINANCE_SECRET_KEY"

Docker Compose (Optional)

Create a docker-compose.yml:

version: '3.8'
services:
  binance-mcp:
    build: .
    environment:
      - BINANCE_API_KEY=${BINANCE_API_KEY}
      - BINANCE_SECRET_KEY=${BINANCE_SECRET_KEY}
    command: [
      "--binance-api-key", "${BINANCE_API_KEY}",
      "--binance-secret-key", "${BINANCE_SECRET_KEY}"
    ]

Then run:

docker-compose up

Development Installation

For development, you can install from source:

git clone https://github.com/bin-mcp/binance-mcp-server.git
cd binance-mcp-server
pip install -e ".[dev]"

⚙️ Configuration

API Requirements

Your Binance API key needs the following permissions:

Futures Trading: For order placement and management
Futures Reading: For account and market data access

MCP Client Setup

This server can be integrated with various MCP clients. Here are configuration examples:

VS Code

Add to your VS Code settings.json:

{
  "mcp": {
    "servers": {
      "binance": {
        "command": "uvx",
        "args": ["--from", "binance_futures_mcp", "binance-mcp-server.exe", "--binance-api-key", "your_api_key", "--binance-secret-key", "your_secret_key"]
      }
    }
  }
}

Cursor

Add to your Cursor configuration file (.cursor/mcp.json):

{
  "servers": {
    "binance": {
      "command": "uvx", 
      "args": ["--from", "binance_futures_mcp", "binance-mcp-server.exe", "--binance-api-key", "your_api_key", "--binance-secret-key", "your_secret_key"]
    }
  }
}

Windsurf

Add to your Windsurf configuration (.windsurf/mcp.json):

{
  "mcpServers": {
    "binance": {
      "command": "uvx",
      "args": ["--from", "binance_futures_mcp", "binance-mcp-server.exe", "--binance-api-key", "your_api_key", "--binance-secret-key", "your_secret_key"]
    }
  }
}

Claude Desktop

Add to your Claude Desktop configuration file:

On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
On Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "binance": {
      "command": "uvx",
      "args": ["--from", "binance_futures_mcp", "binance-mcp-server.exe", "--binance-api-key", "your_api_key", "--binance-secret-key", "your_secret_key"]
    }
  }
}

Configuration Notes

No path needed: With PyPI installation, you don't need to specify paths or working directories
Set API credentials: Replace your_api_key and your_secret_key with your actual Binance API credentials
Alternative commands: You can also use uvx binance_futures_mcp or python -m binance_mcp
Security: For production use, consider storing credentials in environment variables

🛠️ Available Tools

The server provides 11 essential tools organized into the following categories:

Account Information

(5 tools)

get_account_info - Get account information
get_balance - Get account balance
get_position_info - Get position information
get_position_mode - Get position mode (Hedge vs. One-way)
get_commission_rate - Get commission rate

Market Data

(6 tools)

get_exchange_info - Get exchange trading rules
get_book_ticker - Get best price/qty on the order book
get_price_ticker - Get latest price for a symbol
get_order_book - Get order book depth
get_klines - Get candlestick data
get_mark_price - Get mark price and funding rate

💡 Example Usage

Place a Market Order

{
  "tool": "place_order",
  "arguments": {
    "symbol": "BTCUSDT",
    "side": "BUY",
    "order_type": "MARKET",
    "quantity": 0.001
  }
}

Place a Limit Order

{
  "tool": "place_order",
  "arguments": {
    "symbol": "BTCUSDT",
    "side": "BUY",
    "order_type": "LIMIT",
    "quantity": 0.001,
    "price": 50000.0,
    "time_in_force": "GTC"
  }
}

Get Account Information

{
  "tool": "get_account_info",
  "arguments": {}
}

Get Market Data

{
  "tool": "get_klines",
  "arguments": {
    "symbol": "BTCUSDT",
    "interval": "1h",
    "limit": 100
  }
}

Get 24hr Price Statistics

{
  "tool": "get_24hr_ticker",
  "arguments": {
    "symbol": "BTCUSDT"
  }
}

Get Taker Buy/Sell Volume Ratio

{
  "tool": "get_taker_buy_sell_volume",
  "arguments": {
    "symbol": "BTCUSDT"
  }
}

🔒 Security

API Key Security

🔐 Your Binance API key and secret remain completely local to your computer. The MCP server runs entirely on your machine; neither the package author nor any third-party remote service can access your credentials.

Key Security Points:

✅ Store credentials in environment variables (recommended) or local config files
✅ Keys are never transmitted unless you publish them
❌ Never commit credentials to version control
❌ Never share screenshots/logs containing credentials
✅ Use API keys with minimal required permissions
✅ IP-whitelist your keys when possible
✅ Consider using Binance Testnet for development

How It Works:

Local Launch: Your editor/terminal launches the MCP server locally:
uvx binance_futures_mcp --binance-api-key $BINANCE_API_KEY --binance-secret-key $BINANCE_SECRET_KEY
Keys Stay Local: Your credentials exist only:
- In your environment variables or local config file
- On your computer's command line/process table
- In MCP process memory during HTTPS calls to Binance
No Telemetry: The package contains zero telemetry or analytics code

Rate Limiting & Error Handling

⚡ Respects Binance's weight-based rate limits
🔄 Automatic order placement rate limiting
🔐 Automatic HMAC SHA256 signature generation
🛡️ Comprehensive error handling with clear messages
✅ Parameter validation before API calls

📚 API Reference

This server implements all endpoints documented in the Binance Futures API:

Base URL: https://fapi.binance.com
API Type: Binance USD-S Margined Futures
Authentication: API Key + HMAC SHA256 Signature
Rate Limits: Respected automatically

For detailed parameter specifications, see the Binance Futures API Documentation.

🔧 Development

Project Structure

binance-mcp-server/
├── src/
│   └── binance_mcp/
│       ├── __init__.py          # Package initialization
│       ├── __main__.py          # CLI entry point
│       ├── server.py            # Main MCP server implementation
│       ├── client.py            # Binance API client
│       ├── handlers.py          # Tool execution handlers
│       ├── tools.py             # Tool definitions (11 trading tools)
│       └── config.py            # Configuration management
├── Dockerfile                   # Docker containerization
├── .dockerignore               # Docker build optimization
├── pyproject.toml              # Project configuration
├── mcp-config.json             # MCP client configuration example
└── README.md                   # Documentation

Architecture Overview

Modular Design: Separated concerns across multiple components
Authentication: Secure API key handling with environment variables
Error Handling: Graceful degradation and comprehensive error management

Running Tests

pytest

Code Formatting

black src/
ruff check src/

❗ Error Codes

Common Binance API error codes you might encounter:

Code	Description
`-1121`	Invalid symbol
`-2019`	Margin is insufficient
`-1116`	Invalid orderType
`-1013`	Filter failure (PRICE_FILTER, LOT_SIZE, etc.)
`-1102`	Mandatory parameter was not sent
`-1003`	Too many requests (rate limit exceeded)

For a complete list, see the Binance API Error Codes.

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

📄 License

MIT License - see LICENSE file for details.

⚠️ Disclaimer

⚠️ IMPORTANT: This software is for educational and development purposes. Trading cryptocurrencies involves substantial risk. Use at your own risk and never trade with money you cannot afford to lose.

💬 Support

For issues and questions:

Check the Binance API Documentation
Review the error codes in the API documentation
Ensure your API credentials have the correct permissions

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Comprehensive Binance Futures trading MCP server with professional trading tools across account management, order execution, market data, and risk management. Features smart ticker caching, secure authentication, and Docker support for seamless integration with MCP clients.

Related MCP Servers

freqtrade-mcp
kukapay
-
security
A
license
-
quality
An MCP server that integrates with the Freqtrade cryptocurrency trading bot.
Last updated -
72
MIT License
Binance MCP Server
mixuechu
A
security
F
license
A
quality
A Model Control Protocol (MCP) server that provides cryptocurrency trading interfaces for Binance exchange, enabling functions like real-time price fetching, account balance queries, order placement/cancellation, and automated arbitrage strategies.
Last updated -
9
6
Binance Bitcoin MCP Tool
MilesCool
A
security
A
license
A
quality
Provides an MCP server that allows large language models to access real-time and historical Bitcoin market data from Binance, including current prices, order book data, recent trades, and price history through a standardized interface.
Last updated -
1
9
2
MIT License
Binance Cryptocurrency MCP
snjyor
A
security
A
license
A
quality
MCP service that provides real-time access to Binance cryptocurrency market data, allowing AI agents to fetch current prices, order books, candlestick charts, and trading statistics through natural language queries.
Last updated -
12
72
29
Apache 2.0

View all related MCP servers

Binance MCP Server

📋 Table of Contents

🚀 Quick Start

✨ Features

📦 Installation

Option 1: PyPI Installation (Recommended)

Option 2: Docker Deployment

Docker Compose (Optional)

Development Installation

⚙️ Configuration

API Requirements

MCP Client Setup

VS Code

Cursor

Windsurf

Claude Desktop

Configuration Notes

🛠️ Available Tools

Account Information

Market Data

💡 Example Usage

Place a Market Order

Place a Limit Order

Get Account Information

Get Market Data

Get 24hr Price Statistics

Get Taker Buy/Sell Volume Ratio

🔒 Security

API Key Security

Key Security Points:

How It Works:

Rate Limiting & Error Handling

📚 API Reference

🔧 Development

Project Structure

Architecture Overview

Running Tests

Code Formatting

❗ Error Codes

🤝 Contributing

📄 License

⚠️ Disclaimer

💬 Support

Related MCP Servers

freqtrade-mcp

Binance MCP Server

Binance Bitcoin MCP Tool

Binance Cryptocurrency MCP

Appeared in Searches

New MCP Servers

MCP directory API