Bin MCP

🚀 Binance MCP Server

This Model Context Protocol (MCP) server offers comprehensive access to Binance Futures API endpoints. It implements all major trading, account management, and market data functionalities as described in the Binance Futures API.

🚀 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

⚠️ Important Note

• With PyPI installation, you don't need to specify paths or working directories.
• Replace your_api_key and your_secret_key with your actual Binance API credentials.
• You can also use uvx binance_futures_mcp or python -m binance_mcp.
• 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

💻 Usage Examples

Basic Usage

Place a Market Order

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

Advanced Usage

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

⚠️ Important Note

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

⚠️ Important Note

• The server respects Binance's weight-based rate limits.
• It has automatic order placement rate limiting.
• It can automatically generate HMAC SHA256 signatures.
• It provides comprehensive error handling with clear messages.
• It validates parameters before API calls.

📚 API Reference

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

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

🔧 Technical Details

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

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 Note

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