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.

• 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

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

Install the official package from PyPI:

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

# Alternative: Using uv for faster package management
uv add binance-mcp-server

💡 Why use the PyPI package?

• ✅ Always up-to-date with latest releases
• ✅ Automatic dependency management
• ✅ Simple installation and updates
• ✅ No need to clone repositories or manage source code

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"

# Start the MCP server (after installing from PyPI)
binance-mcp-server --api-key $BINANCE_API_KEY --api-secret $BINANCE_API_SECRET --binance-testnet

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

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

📝 Note: This section is for contributors and developers who want to modify the source code. Regular users should install from PyPI using the instructions above.

# 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 (choose one)
# Option A: Using uv (if available)
uv install --dev

# Option B: Using pip
pip install -e .
pip install pytest  # for testing

# 4. Set up pre-commit hooks (optional)
pip install pre-commit
pre-commit install --hook-type commit-msg

# 5. Run tests to verify setup
pytest

# 6. Start development server
python -m binance_mcp_server.cli

# 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

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

Check our GitHub Issues for the latest development priorities:

• Enhanced Trading Tools - Order cancellation, modification, and advanced order types
• Portfolio Management - Advanced portfolio analytics and asset allocation tools
• Risk Management Extensions - Margin monitoring, leverage management, and liquidation alerts
• Market Data Enhancements - Historical data, technical indicators, and market analysis
• Alert System - Price notifications and position monitoring
• Documentation & Examples - Comprehensive guides and use case examples

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

💡 For Regular Use: Most users should install via pip install binance-mcp-server instead of cloning this repository.

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

# Install dependencies and set up environment (choose one)
# Option A: Using uv (if available)
uv install --dev

# Option B: Using pip
pip install -e .
pip install pytest pre-commit

# 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"

• 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

• MCP Protocol Compliance: Full adherence to Model Context Protocol 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: Comprehensive input validation and secure error handling

This server implements comprehensive security measures following Model Context Protocol best practices:

• Enhanced Input Validation: All inputs are validated and sanitized
• Secure Error Handling: Error messages are sanitized to prevent information leakage
• Rate Limiting: Built-in protection against API abuse
• Credential Protection: No sensitive data logged or exposed
• Audit Logging: Comprehensive security event tracking

• 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

# 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"

# Optional: Configure security features
export MCP_RATE_LIMIT_ENABLED="true"
export MCP_MAX_REQUESTS_PER_MINUTE="60"

📖 Read Full Security Documentation - Comprehensive security guidelines and best practices.

# Get real-time Bitcoin price
{
    "name": "get_ticker_price",
    "arguments": {
        "symbol": "BTCUSDT"
    }
}

# Get 24-hour ticker statistics for Ethereum
{
    "name": "get_ticker", 
    "arguments": {
        "symbol": "ETHUSDT"
    }
}

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

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

# Get account snapshot
{
    "name": "get_account_snapshot",
    "arguments": {
        "account_type": "SPOT"
    }
}

# Create a limit buy order for Ethereum
{
    "name": "create_order",
    "arguments": {
        "symbol": "ETHUSDT",
        "side": "BUY", 
        "order_type": "LIMIT",
        "quantity": 0.1,
        "price": 2000.00
    }
}

# Get order history for a symbol
{
    "name": "get_orders",
    "arguments": {
        "symbol": "ETHUSDT"
    }
}

# Calculate profit and loss
{
    "name": "get_pnl",
    "arguments": {}
}

# Get position information
{
    "name": "get_position_info",
    "arguments": {}
}

• MCP Server Framework - FastMCP integration and basic structure
• MCP Protocol Compliance - Enhanced security and best practices implementation
• Documentation & Planning - Comprehensive tool specifications
• Authentication System - Secure Binance API integration
• Basic Tools Implementation - Essential trading and account tools (15 tools)
• Security Features - Input validation, error sanitization, rate limiting

• Order Management - Basic order creation and history
• Market Data Integration - Real-time price feeds and order books
• Portfolio Analytics - Basic P&L tracking and position info
• Advanced Order Types - Stop-loss, take-profit, OCO orders
• Order Cancellation - Cancel and modify existing orders
• Enhanced Risk Management - Advanced margin monitoring

• Advanced Analytics - Technical indicators and market insights
• Alert System - Price notifications and position monitoring
• Strategy Tools - DCA, grid trading, and automation helpers
• Multi-account Support - Cross-margin, isolated margin accounts

• Tool Coverage: 15/15 core tools implemented ✅
• Test Coverage: >90% code coverage target (currently 38 tests passing)
• Security Compliance: MCP best practices implemented ✅
• Performance: <100ms average API response time
• Community: Growing GitHub engagement and contributions
• Production Usage: Stable package releases on PyPI

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

• Complete Documentation - Comprehensive guides and tutorials

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

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

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

• Testing Environment: Always use Binance testnet for development and testing
• Financial Risk: Only trade with funds you can afford to lose
• Due Diligence: Conduct thorough testing before deploying to live trading
• No Liability: Developers assume no responsibility for financial losses

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

Built with ❤️ by the crypto development community