Configuration Guide¶

Environment Variables¶

The Binance MCP Server uses environment variables for configuration. This approach ensures security by keeping sensitive credentials out of source code.

Required Variables¶

Variable	Description	Example
`BINANCE_API_KEY`	Your Binance API key	`abc123def456...`
`BINANCE_API_SECRET`	Your Binance API secret	`xyz789uvw012...`

Optional Variables¶

Variable	Default	Description	Options
`BINANCE_TESTNET`	`false`	Use Binance testnet	`true`, `false`

Configuration Methods¶

Method 1: Environment Variables (Recommended)¶

Linux/macOSWindows PowerShellWindows Command Prompt

export BINANCE_API_KEY="your_api_key_here"
export BINANCE_API_SECRET="your_api_secret_here"
export BINANCE_TESTNET="true"

$env:BINANCE_API_KEY="your_api_key_here"
$env:BINANCE_API_SECRET="your_api_secret_here"
$env:BINANCE_TESTNET="true"

set BINANCE_API_KEY=your_api_key_here
set BINANCE_API_SECRET=your_api_secret_here
set BINANCE_TESTNET=true

Method 2: .env File¶

Create a .env file in your project directory:

# .env file
BINANCE_API_KEY=your_api_key_here
BINANCE_API_SECRET=your_api_secret_here
BINANCE_TESTNET=true

The server will automatically load the .env file using python-dotenv.

Method 3: MCP Client Configuration¶

When configuring MCP clients like Claude Desktop, include environment variables in the configuration:

{
  "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"
      }
    }
  }
}

API Key Management¶

Creating API Keys¶

Login to Binance: Visit binance.com or binance.us
Navigate to API Management: Account → API Management
Create New Key: Click "Create API" → "System generated"
Set Permissions:
✅ Enable Reading (Required for market data)
✅ Enable Spot Trading (Required for trading)
✅ Enable Futures (Optional, for futures trading)
❌ Enable Withdrawals (Not recommended for security)

API Key Security¶

IP Restrictions (Recommended)¶

Add your server's IP address to the allowed list
Use "Restrict access to trusted IPs only"
Update IP restrictions when your server IP changes

Key Rotation¶

Rotate API keys regularly (monthly/quarterly)
Delete unused API keys
Monitor API key usage in Binance account

Permissions¶

Only enable necessary permissions
Avoid enabling withdrawal permissions unless absolutely required
Use separate keys for different applications

Testnet vs Production¶

Testnet Configuration¶

export BINANCE_TESTNET="true"

URL: https://testnet.binance.vision
Purpose: Development and testing with fake money
Benefits: Safe experimentation, no real financial risk
Limitations: Reduced functionality, fake data

Production Configuration¶

export BINANCE_TESTNET="false"  # or omit entirely

URL: https://api.binance.com
Purpose: Live trading with real money
Benefits: Full functionality, real market data
Requirements: Extra caution, proper risk management

Server Configuration¶

Command Line Options¶

binance-mcp-server [OPTIONS]

Option	Description	Default	Example
`--transport`	Transport method	`stdio`	`--transport streamable-http`
`--port`	Port for HTTP transport	`8000`	`--port 3000`
`--host`	Host for HTTP transport	`localhost`	`--host 0.0.0.0`
`--log-level`	Logging level	`INFO`	`--log-level DEBUG`

Transport Options¶

STDIO (Default)¶

binance-mcp-server

- Best for: MCP clients (Claude, etc.) - Communication: stdin/stdout - Use case: Production MCP integration

HTTP¶

binance-mcp-server --transport streamable-http --port 8000

- Best for: Testing and development - Communication: HTTP POST requests - Use case: API testing, debugging

SSE (Server-Sent Events)¶

binance-mcp-server --transport sse --port 8080

- Best for: Real-time applications - Communication: Server-sent events - Use case: Live data streaming

Logging Configuration¶

Log Levels¶

Level	Description	Use Case
`DEBUG`	Detailed debugging information	Development, troubleshooting
`INFO`	General information messages	Production monitoring
`WARNING`	Warning messages	Error monitoring
`ERROR`	Error messages only	Minimal logging

Example Log Output¶

# INFO level (default)
2024-01-01 12:00:00 - binance_mcp_server.server - INFO - Starting Binance MCP Server with stdio transport
2024-01-01 12:00:01 - binance_mcp_server.utils - INFO - Successfully initialized Binance client (testnet: True)
2024-01-01 12:00:02 - binance_mcp_server.tools.get_ticker_price - INFO - Tool called: get_ticker_price with symbol=BTCUSDT

# DEBUG level
2024-01-01 12:00:00 - binance_mcp_server.config - DEBUG - Loading configuration from environment
2024-01-01 12:00:00 - binance_mcp_server.config - DEBUG - API key loaded: abc123***
2024-01-01 12:00:00 - binance_mcp_server.config - DEBUG - Testnet mode: True

Configuration Validation¶

The server validates configuration on startup and provides helpful error messages:

Missing API Key¶

Error: Invalid Binance configuration: BINANCE_API_KEY environment variable is required

Missing API Secret¶

Error: Invalid Binance configuration: BINANCE_API_SECRET environment variable is required

Invalid API Credentials¶

Error: Binance API error during client initialization: API-key format invalid

Network Issues¶

Error: Binance request error during client initialization: Connection timeout

Production Deployment¶

Docker Configuration¶

FROM python:3.10-slim

WORKDIR /app

# Install the package
RUN pip install binance-mcp-server

# Set environment variables
ENV BINANCE_TESTNET=false

# Command to run the server
CMD ["binance-mcp-server"]

# Run with environment variables
docker run -e BINANCE_API_KEY="your_key" \
           -e BINANCE_API_SECRET="your_secret" \
           -e BINANCE_TESTNET="false" \
           your-binance-mcp-server

Environment-Specific Configuration¶

Development¶

# Development environment
export BINANCE_TESTNET="true"
export LOG_LEVEL="DEBUG"
binance-mcp-server --log-level DEBUG

Staging¶

# Staging environment
export BINANCE_TESTNET="true"
export LOG_LEVEL="INFO"
binance-mcp-server --log-level INFO

Production¶

# Production environment
export BINANCE_TESTNET="false"
export LOG_LEVEL="WARNING"
binance-mcp-server --log-level WARNING

Health Checks¶

The server provides basic health checking through configuration validation:

from binance_mcp_server.config import BinanceConfig

def health_check():
    try:
        config = BinanceConfig()
        if config.is_valid():
            return {"status": "healthy", "testnet": config.testnet}
        else:
            return {"status": "unhealthy", "errors": config.get_validation_errors()}
    except Exception as e:
        return {"status": "error", "message": str(e)}

Troubleshooting Configuration¶

Common Issues¶

1. Environment Variables Not Set¶

Problem: Variables set in terminal but not visible to the process

Solutions: - Use .env file instead - Check if variables are exported: export VARIABLE=value - Restart terminal/IDE after setting variables

2. Wrong Testnet Setting¶

Problem: Using production keys with testnet or vice versa

Solutions: - Verify BINANCE_TESTNET matches your API key type - Testnet keys only work with testnet endpoints - Production keys only work with production endpoints

3. API Key Permissions¶

Problem: API operations failing due to insufficient permissions

Solutions: - Check API key permissions in Binance account - Enable "Reading" and "Spot Trading" permissions - Avoid enabling "Withdrawals" unless necessary

4. IP Restrictions¶

Problem: API calls failing due to IP restrictions

Solutions: - Add your server IP to allowed list in Binance - Remove IP restrictions for testing - Use VPN if server IP changes frequently

Configuration Testing¶

Test your configuration before deployment:

# Test with ticker price (read-only operation)
binance-mcp-server --transport streamable-http &
curl -X POST http://localhost:8000/call \
  -H "Content-Type: application/json" \
  -d '{"tool": "get_ticker_price", "arguments": {"symbol": "BTCUSDT"}}'

Expected successful response:

{
  "success": true,
  "data": {
    "symbol": "BTCUSDT", 
    "price": 42350.50
  },
  "timestamp": 1704067200000
}