Skip to main content
Glama

binance-futures-mcp

by alexcandrabersiva
GitHub
Python
MIT License
2
  • Apple
OverviewInspectNewEndpointsSchemaRelated 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

  • 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

  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 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:

  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 (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

  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

                    • freqtrade-mcp

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

                    • 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
                      0
                      3
                      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
                      33
                      30
                      Apache 2.0

                    View all related MCP servers

                    Appeared in Searches

                    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