Binance MCP Server 🚀

Created By

AnalyticAce7 months ago

Unofficial tools and server implementation for Binance's Model Context Protocol (MCP). Designed to support developers building crypto trading AI Agents.

# agent

# finance

Overview Content Tools Comments

Content

Binance MCP Server 🚀

A powerful Model Context Protocol (MCP) server that enables AI agents to interact seamlessly with the Binance cryptocurrency exchange. This server provides a comprehensive suite of trading tools, market data access, and account management capabilities through the standardized MCP interface.

🎯 Key Features

Secure Authentication: API key-based authentication with Binance
Real-time Market Data: Live price feeds, order book data, and market statistics
Trading Operations: Place, modify, and cancel orders across spot and futures markets
Portfolio Management: Account balance tracking, position monitoring, and P&L analysis
Smart Notifications: Real-time alerts for price movements, order fills, and market events
Risk Management: Built-in safeguards and validation for trading operations

🚀 Quick Start

Prerequisites

Python 3.10+ installed on your system
Binance account with API access enabled
API credentials (API Key & Secret) from your Binance account

1️⃣ Installation

# Install using uv (recommended for Python package management)
uv add binance-mcp-server

# Alternative: Install using pip
pip install binance-mcp-server

2️⃣ Configuration

Set up your Binance API credentials as environment variables:

# 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 and testing
export BINANCE_TESTNET="true"

3️⃣ Launch Server

# Start the MCP server
binance_mcp_server --api-key $BINANCE_API_KEY --api-secret $BINANCE_API_SECRET --binance-testnet $BINANCE_TESTNET

4️⃣ Connect Your AI Agent

Configure your AI agent (Claude, GPT-4, or custom bot) to connect to the MCP server:

{
  "mcpServers": {
    "binance": {
      "command": "binance_mcp_server",
      "args": [
        "--api-key": "your_api_key",
        "--api-secret": "your_secret",
        "--binance-testnet": "false" # Set to true for testnet
      ]
    }
  }
}

📚 Available Tools

Our MCP server provides 26 comprehensive trading tools that enable AI agents to perform advanced cryptocurrency trading operations. Each tool follows the Model Context Protocol standard for seamless integration.

🏦 Account & Portfolio Management

Tool	Purpose	Alternatives
`get_balance`	Retrieve account balances (spot, margin, futures)	`fetch_account_balance`, `account_balance_info`
`get_portfolio`	Fetch holdings, positions, and asset allocation	`fetch_portfolio`, `portfolio_info`
`get_account_snapshot`	Point-in-time account state snapshot	`fetch_account_snapshot`, `account_state`
`get_fee_info`	Trading, withdrawal, and funding fee rates	`fetch_fee_info`, `fee_rates`
`get_available_assets`	List all tradable cryptocurrencies	`fetch_available_assets`, `asset_list`

📊 Market Data & Analysis

Tool	Purpose	Alternatives
`get_market_data`	Real-time and historical price/volume data	`fetch_market_data`, `market_data_feed`
`get_ticker`	Latest price and 24h statistics	`fetch_ticker`, `ticker_info`
`get_order_book`	Current order book (bids/asks)	`fetch_order_book`, `orderbook_info`
`get_asset_price`	Current or historical asset pricing	`fetch_asset_price`, `asset_price_info`

💱 Trading Operations

Tool	Purpose	Alternatives
`place_order`	Submit buy/sell orders (market, limit, stop)	`create_order`, `submit_order`
`cancel_order`	Cancel open orders by ID or symbol	`remove_order`, `revoke_order`
`get_order_status`	Retrieve order status and details	`fetch_order_status`, `order_info`
`list_orders`	List open, filled, or cancelled orders	`get_orders`, `fetch_order_list`
`get_trade_history`	Historical trades executed by user	`fetch_trade_history`, `trade_log`

📈 Performance & Analytics

Tool	Purpose	Alternatives
`get_pnl`	Calculate realized/unrealized profit and loss	`fetch_pnl`, `profit_and_loss`
`get_position_info`	Open positions details (size, entry, liquidation)	`fetch_position_info`, `position_details`
`get_transaction_history`	Deposits, withdrawals, and transfers log	`fetch_transaction_history`, `transaction_log`
`get_dividends`	Dividend payments and history	`fetch_dividends`, `dividend_history`

🛡️ Risk Management & Margins

Tool	Purpose	Alternatives
`get_risk_metrics`	Margin level, liquidation risk, leverage info	`fetch_risk_metrics`, `risk_info`
`get_funding_rates`	Futures/perpetual contract funding rates	`fetch_funding_rates`, `funding_info`
`get_leverage_brackets`	Allowed leverage and margin requirements	`fetch_leverage_brackets`, `leverage_info`
`get_margin_interest`	Interest rates and accrued interest	`fetch_margin_interest`, `margin_interest_info`
`get_liquidation_history`	Past liquidation events	`fetch_liquidation_history`, `liquidation_log`
`get_borrow_history`	Borrowed funds and repayment history	`fetch_borrow_history`, `borrow_log`

🔄 Advanced Operations

Tool	Purpose	Alternatives
`get_asset_transfer`	Transfer assets between accounts	`fetch_asset_transfer`, `transfer_funds`
`get_withdrawal_status`	Check withdrawal request status	`fetch_withdrawal_status`, `withdrawal_info`

🔧 Configuration

Environment Variables

Variable	Description	Required	Default
`BINANCE_API_KEY`	Your Binance API key	✅	-
`BINANCE_API_SECRET`	Your Binance API secret	✅	-
`BINANCE_TESTNET`	Use testnet environment	❌	`false`

🛠️ Development

Development Environment Setup

# 1. Clone the repository
git clone https://github.com/AnalyticAce/binance-mcp-server.git
cd binance-mcp-server

# 2. Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# 3. Install development dependencies
uv install --dev

# 4. Set up pre-commit hooks (required for development)
pre-commit install --hook-type commit-msg

# 5. Run tests to verify setup
pytest

# 6. Start development server with hot-reload
python -m binance_mcp_server.cli --dev --reload

Project Structure

binance-mcp-server/
├── 📦 binance_mcp_server/         # Main package
│   ├── __init__.py                # Package initialization  
│   ├── server.py                  # MCP server implementation
│   ├── cli.py                     # Command-line interface
│   ├── tools/                     # MCP tool implementations
│   │   ├── __init__.py
│   │   ├── account.py             # Account management tools
│   │   ├── trading.py             # Trading operation tools
│   │   ├── market_data.py         # Market data tools
│   │   └── risk.py                # Risk management tools
│   └── utils/                     # Utility modules
│       ├── __init__.py
│       ├── binance_client.py      # Binance API client wrapper
│       └── validators.py          # Input validation helpers
├── 📚 docs/                       # Documentation
│   ├── setup.md                   # Detailed setup guide
│   ├── overview.md                # API overview and examples
│   ├── contributing.md            # Contributing guidelines
│   └── suggested_mcp_tools.md     # Tool specifications
├── 🧪 tests/                      # Test suite
│   ├── __init__.py
│   ├── test_server.py             # Server tests
│   ├── test_tools/                # Tool-specific tests
│   └── conftest.py                # Test configuration
├── 📄 scripts/                    # Deployment and utility scripts
├── ⚙️ pyproject.toml               # Project configuration
├── 📖 README.md                   # This file
└── 📄 LICENSE                     # MIT license

Testing Strategy

# Run all tests
pytest

# Run tests with coverage report
pytest --cov=binance_mcp_server --cov-report=html

# Run specific test category
pytest tests/test_tools/test_account.py -v

🤝 Contributing

We welcome contributions from the crypto and AI development community! Here's how you can help:

🎯 Current Priorities

Check our GitHub Issues for the latest development priorities:

Account Management Tools (#6-8) - get_balance, get_portfolio, get_fee_info
Market Data Integration (#9-13) - Real-time data feeds and historical analysis
Trading Operations (#14-18) - Order management and execution
Portfolio Analytics (#19-22) - Performance tracking and risk metrics
Alert System (#23-24) - Price and position monitoring
Risk Management (#25-26) - Margin and liquidation safeguards

📋 Contribution Guidelines

Fork & Branch: Create a feature branch from main
Code: Follow our coding standards
Pre-commit Hooks: Install and configure pre-commit hooks for commit message validation
Test: Add tests for new features (aim for >80% coverage)
Document: Update documentation for user-facing changes
Review: Submit a pull request for review

🔧 Development Setup for Contributors

# Clone your fork
git clone https://github.com/your-username/binance-mcp-server.git
cd binance-mcp-server

# Install dependencies and set up environment
uv install --dev

# Install pre-commit hooks (enforces commit message conventions)
pre-commit install --hook-type commit-msg

# Make your changes and commit using conventional format
git commit -m "feat(tools): add new market data tool"

🏷️ Issue Labels

good first issue - Perfect for newcomers
enhancement - New features and improvements
bug - Something isn't working correctly
documentation - Documentation updates needed
help wanted - Community assistance requested

📝 Development Standards

Pre-commit Hooks: Required for all contributors to ensure commit message consistency
Type Hints: Full type annotations required
Testing: pytest with >80% coverage target
Commits: Conventional commit format (feat:, fix:, etc.) enforced by pre-commit hooks
Documentation: Google-style docstrings

🔒 Security & Best Practices

🛡️ API Security

Credential Management: Never commit API keys to version control
Testnet First: Always test with Binance testnet before live trading
Rate Limiting: Built-in respect for Binance API rate limits
Input Validation: Comprehensive validation of all trading parameters
Audit Logging: Complete audit trail of all operations

🔐 Environment Security

# Use environment variables for sensitive data
export BINANCE_API_KEY="your_key_here"
export BINANCE_API_SECRET="your_secret_here"

# Enable testnet for development
export BINANCE_TESTNET="true"

💡 Usage Examples

📊 Market Data Queries

# Get real-time Bitcoin price and market data
{
    "name": "get_market_data",
    "arguments": {
        "symbol": "BTCUSDT",
        "interval": "1h"
    }
}

# Check current order book for Ethereum
{
    "name": "get_order_book", 
    "arguments": {
        "symbol": "ETHUSDT",
        "limit": 10
    }
}

💰 Account Management

# Check account balances
{
    "name": "get_balance",
    "arguments": {
        "account_type": "spot"
    }
}

# Get portfolio overview
{
    "name": "get_portfolio",
    "arguments": {
        "include_positions": true
    }
}

🛒 Trading Operations

# Place a limit buy order for Ethereum
{
    "name": "place_order",
    "arguments": {
        "symbol": "ETHUSDT",
        "side": "BUY", 
        "type": "LIMIT",
        "quantity": "0.1",
        "price": "2000.00",
        "timeInForce": "GTC"
    }
}

# Cancel an open order
{
    "name": "cancel_order",
    "arguments": {
        "symbol": "ETHUSDT", 
        "orderId": "12345678"
    }
}

📈 Performance Analysis

# Calculate profit and loss
{
    "name": "get_pnl",
    "arguments": {
        "symbol": "BTCUSDT",
        "timeframe": "24h"
    }
}

# Get trading history
{
    "name": "get_trade_history",
    "arguments": {
        "symbol": "ETHUSDT",
        "limit": 50
    }
}

🎯 Roadmap

🚀 Phase 1: Core Foundation

MCP Server Framework - FastMCP integration and basic structure
Documentation & Planning - Comprehensive tool specifications
Authentication System - Secure Binance API integration
Basic Tools Implementation - Essential trading and account tools

📊 Phase 2: Trading Operations

Order Management - Complete buy/sell order lifecycle
Market Data Integration - Real-time feeds and historical data
Portfolio Analytics - P&L tracking and performance metrics
Risk Management - Margin monitoring and position limits

🔥 Phase 3: Advanced Features

Advanced Analytics - Technical indicators and market insights
Alert System - Price notifications and position monitoring
Strategy Tools - DCA, grid trading, and automation helpers

📈 Success Metrics

Tool Coverage: 26/26 core tools implemented ✅
Test Coverage: >90% code coverage target
Performance: <100ms average API response time
Community: 1000+ GitHub stars, 100+ contributors
Production Usage: 10,000+ monthly active installations

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support & Community

📚 Documentation & Resources

Complete Documentation - Comprehensive guides and tutorials

💬 Get Help

Report Issues - Bug reports and feature requests
Discussions - Community Q&A and ideas
Email Support - Technical questions and partnership inquiries

🏷️ Quick Help Tags

When creating issues, please use these labels to help us respond faster:

bug - Something isn't working
enhancement - Feature requests
question - General questions
documentation - Docs improvements
good first issue - Perfect for newcomers

⚠️ Legal Disclaimer

Important Notice: This software is provided for educational and development purposes only. Cryptocurrency trading involves substantial risk of financial loss.