Setup Guide

August 6, 2025 · View on GitHub

Installation

Prerequisites

  • Python 3.10+ - Required for modern typing and async support
  • Binance Account - With API access enabled
  • API Credentials - API Key and Secret from Binance

Step 1: Install the Package

The easiest way to get started is by installing the official package from PyPI:

=== "pip (Recommended)" bash # Install the latest stable release pip install binance-mcp-server

=== "uv (Fast Package Manager)" bash # Install using uv for fast, reliable package management uv add binance-mcp-server

=== "Development Installation" bash # Only for contributors - regular users should use pip install above git clone https://github.com/AnalyticAce/BinanceMCPServer.git cd BinanceMCPServer pip install -e .

💡 Benefits of PyPI Installation:

  • ✅ Always the latest stable version
  • ✅ Automatic dependency management
  • ✅ Easy updates with pip install --upgrade binance-mcp-server
  • ✅ No need to manage source code

Configuration

Step 2: Binance API Setup

  1. Login to Binance: Go to binance.com or binance.us

  2. Create API Key:

    • Navigate to Account → API Management
    • Click "Create API"
    • Choose "System generated" API key

  3. Configure Permissions:

    ✅ Enable Reading      (Required for market data)
✅ Enable Spot Trading (Required for trading operations)  
✅ Enable Futures      (Optional, for futures trading)
❌ Enable Withdrawals  (Not recommended for security)

  4. IP Restrictions (Recommended):

    • Add your server's IP address
    • Use "Restrict access to trusted IPs only"

Step 3: Environment Variables

Set up your API credentials as environment variables:

=== "Linux/macOS" ```bash # Required: Your Binance API credentials export BINANCE_API_KEY="your_api_key_here" export BINANCE_API_SECRET="your_api_secret_here"

# Recommended: Use testnet for development
export BINANCE_TESTNET="true"
```

=== "Windows (PowerShell)" ```powershell # Required: Your Binance API credentials
env:BINANCEAPIKEY="yourapikeyhere"env:BINANCE_API_KEY="your_api_key_here" env:BINANCE_API_SECRET="your_api_secret_here"

# Recommended: Use testnet for development
$env:BINANCE_TESTNET="true"
```

=== ".env File" bash # Create a .env file in your project directory BINANCE_API_KEY=your_api_key_here BINANCE_API_SECRET=your_api_secret_here BINANCE_TESTNET=true

Configuration Options

VariableRequiredDefaultDescription
BINANCE_API_KEY✅ YesNoneYour Binance API key
BINANCE_API_SECRET✅ YesNoneYour Binance API secret
BINANCE_TESTNET❌ NofalseUse testnet environment

Running the Server

Step 4: Start the Server

=== "STDIO (MCP Clients)" ```bash # Default mode for MCP clients (Claude, etc.) - using PyPI installation binance-mcp-server

# With custom log level
binance-mcp-server --log-level DEBUG
```

=== "HTTP (Testing)" ```bash # For testing and development binance-mcp-server --transport streamable-http --port 8000

# Custom host and port
binance-mcp-server --transport streamable-http --host 0.0.0.0 --port 3000
```

=== "SSE (Server-Sent Events)" bash # Server-sent events transport binance-mcp-server --transport sse --port 8080

Command Line Options

binance-mcp-server [OPTIONS]

Options:
  --api-key, -k TEXT               Binance API key (or set BINANCE_API_KEY env var)
  --api-secret, -s TEXT            Binance API secret (or set BINANCE_API_SECRET env var)  
  --binance-testnet, -t            Use testnet environment (recommended for testing)
  --transport [stdio|streamable-http|sse]  Transport method (default: stdio)
  --port INTEGER                   Port for HTTP transport (default: 8000)
  --host TEXT                     Host for HTTP transport (default: localhost)
  --log-level [DEBUG|INFO|WARNING|ERROR]  Set logging level (default: INFO)
  --help                          Show help message

MCP Client Configuration

Claude Desktop Configuration

Add to your Claude Desktop configuration file:

=== "macOS" json // ~/Library/Application Support/Claude/claude_desktop_config.json { "mcpServers": { "binance": { "command": "binance-mcp-server", "args": [], "env": { "BINANCE_API_KEY": "your_api_key_here", "BINANCE_API_SECRET": "your_api_secret_here", "BINANCE_TESTNET": "true" } } } }

=== "Windows" json // %APPDATA%\Claude\claude_desktop_config.json { "mcpServers": { "binance": { "command": "binance-mcp-server", "args": [], "env": { "BINANCE_API_KEY": "your_api_key_here", "BINANCE_API_SECRET": "your_api_secret_here", "BINANCE_TESTNET": "true" } } } }

Other MCP Clients

For other MCP clients, use the STDIO transport:

# Start server in STDIO mode
binance-mcp-server

The server will communicate via stdin/stdout for MCP protocol messages.

Verification

Step 5: Test Your Setup

Test the server connection:

=== "HTTP Testing" ```bash # Start server in HTTP mode binance-mcp-server --transport streamable-http --port 8000

# Test with curl (in another terminal)
curl -X POST http://localhost:8000/call \
  -H "Content-Type: application/json" \
  -d '{"tool": "get_ticker_price", "arguments": {"symbol": "BTCUSDT"}}'
```

=== "Python Testing" ```python import os from binance_mcp_server.tools.get_ticker_price import get_ticker_price

# Set environment variables
os.environ["BINANCE_API_KEY"] = "your_key"
os.environ["BINANCE_API_SECRET"] = "your_secret"
os.environ["BINANCE_TESTNET"] = "true"

# Test a simple API call
result = get_ticker_price("BTCUSDT")
print(f"BTC Price: ${result['data']['price']}")
```

Troubleshooting

Common Issues

❌ Configuration Errors

Error: Invalid Binance configuration: BINANCE_API_KEY environment variable is required

Solution: Ensure environment variables are set correctly

❌ API Authentication Errors

Error: API-key format invalid

Solutions:

  • Verify API key and secret are correct
  • Check API key permissions in Binance account
  • Ensure IP restrictions allow your server IP

❌ Rate Limit Errors

Error: API rate limit exceeded

Solutions:

  • Wait a few minutes before retrying
  • Reduce request frequency
  • Contact Binance support for higher limits

❌ Network Errors

Error: Connection timeout

Solutions:

  • Check internet connectivity
  • Verify firewall settings
  • Try using testnet first

Testnet vs Production

EnvironmentAPI Base URLPurpose
Testnethttps://testnet.binance.visionDevelopment & Testing
Productionhttps://api.binance.comLive Trading

!!! warning "Important" Always start with testnet (BINANCE_TESTNET=true) for development and testing. Testnet uses fake money and allows safe experimentation.

Logging

Enable debug logging for troubleshooting:

binance-mcp-server --log-level DEBUG

Log output includes:

  • API requests and responses
  • Rate limiting status
  • Error details and stack traces
  • Configuration validation results

Next Steps