Skip to main content
Glama

binance-futures-mcp

by alexcandrabersiva
GitHub
Python
MIT License
  • Apple
OverviewInspectNewSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

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

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

✨ Features

  • 17 essential trading tools across 2 categories (Account Information and Market Data)
  • Smart ticker data caching with 5-minute refresh cycle
  • Proper authentication handling (rejects unauthenticated requests)
  • Active symbol filtering (excludes delisted tokens)
  • Error handling and graceful degradation
  • Real-time market data access
  • Complete order management suite
  • Risk management tools

📦 Installation

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

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

🛠️ Available Tools

The server provides 17 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

(12 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_24hr_ticker - Get 24hr price change statistics
  • get_top_gainers_losers - Get top gainers and losers
  • get_market_overview - Get overall market statistics
  • get_order_book - Get order book depth
  • get_klines - Get candlestick data
  • get_mark_price - Get mark price and funding rate
  • get_aggregate_trades - Get compressed/aggregate trades list
  • get_funding_rate_history - Get funding rate history
  • get_taker_buy_sell_volume - Get taker buy/sell volume ratio

💡 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:
  1. 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
  2. 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
  3. 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 (17 trading tools) │ ├── cache.py # Smart ticker data caching │ └── 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
  • Smart Caching: 5-minute ticker cache with background refresh
  • Authentication: Secure API key handling with environment variables
  • Error Handling: Graceful degradation and comprehensive error management
  • Active Symbol Filtering: Excludes delisted tokens automatically

Running Tests

pytest

Code Formatting

black src/ ruff check src/

❗ Error Codes

Common Binance API error codes you might encounter:

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

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

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. 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
A
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.

  1. 📋 Table of Contents
    1. 🚀 Quick Start
      1. ✨ Features
        1. 📦 Installation
          1. Option 1: PyPI Installation (Recommended)
          2. Option 2: Docker Deployment
          3. Development Installation
        2. ⚙️ Configuration
          1. API Requirements
          2. MCP Client Setup
          3. Configuration Notes
        3. 🛠️ Available Tools
          1. Account Information
          2. Market Data
        4. 💡 Example Usage
          1. Place a Market Order
          2. Place a Limit Order
          3. Get Account Information
          4. Get Market Data
          5. Get 24hr Price Statistics
          6. Get Taker Buy/Sell Volume Ratio
        5. 🔒 Security
          1. API Key Security
          2. Rate Limiting & Error Handling
        6. 📚 API Reference
          1. 🔧 Development
            1. Project Structure
            2. Running Tests
            3. Code Formatting
          2. ❗ Error Codes
            1. 🤝 Contributing
              1. 📄 License
                1. ⚠️ Disclaimer
                  1. 💬 Support

                    Related MCP Servers

                    • XTBApiServer

                      sharplygroup
                      -
                      security
                      F
                      license
                      -
                      quality
                      An MCP server that exposes the XTB trading API, allowing users to interact with their XTB trading accounts through the Model Context Protocol to perform operations like account management, market data retrieval, and trade execution.
                      Last updated -
                      6
                      TypeScript

                    • Armor Crypto MCPofficial

                      armorwallet
                      A
                      security
                      A
                      license
                      A
                      quality
                      An MCP server providing unified access to blockchain operations, bridging, swapping, and crypto trading strategies for AI agents.
                      Last updated -
                      20
                      141
                      Python
                      GPL 3.0
                      • Apple
                      • Linux

                    • freqtrade-mcp

                      kukapay
                      -
                      security
                      A
                      license
                      -
                      quality
                      An MCP server that integrates with the Freqtrade cryptocurrency trading bot.
                      Last updated -
                      16
                      Python
                      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
                      Python

                    View all related MCP servers

                    New MCP Servers

                    MCP directory API

                    We provide all the information about MCP servers via our MCP API.

                    curl -X GET 'https://glama.ai/api/mcp/v1/servers/alexcandrabersiva/bin-mcp'

                    If you have feedback or need assistance with the MCP directory API, please join our Discord server