Hummingbot MCP Server¶

The Hummingbot Model Context Protocol (MCP) Server enables AI assistants like Claude and Gemini to interact with Hummingbot for automated cryptocurrency trading across multiple exchanges.

GitHub Repository: github.com/hummingbot/mcp

Overview¶

The MCP Server acts as a bridge between AI language models and the Hummingbot trading platform, enabling programmatic interaction with cryptocurrency trading infrastructure. This allows AI assistants to manage trading operations, analyze portfolios, and execute strategies on behalf of users.

Tutorial Videos¶

Part 1: Introduction to Hummingbot MCP Server¶

Part 2: Building AI Trading Agents¶

What is Model Context Protocol (MCP)?¶

Model Context Protocol is an open standard that enables AI assistants to securely interact with external systems and data sources. In the context of Hummingbot, MCP allows AI models to:

Access real-time trading data
Execute trading operations
Manage portfolios across multiple exchanges
Analyze market conditions
Monitor trading performance

Key Features¶

The Hummingbot MCP Server provides the following capabilities:

🏦 Account Management¶

Connect and manage multiple exchange accounts
Retrieve account information and credentials
Monitor account status across exchanges

💰 Portfolio Tracking¶

View real-time balance across all connected exchanges
Track portfolio performance and P&L
Analyze asset distribution and allocation

📊 Order Management¶

Place buy and sell orders on any supported exchange
Cancel existing orders
Monitor order status and execution
View order history and fills

📈 Position Management¶

Track open positions for derivatives trading
Monitor position sizes and unrealized P&L
Close positions programmatically

🔍 Market Data Access¶

Retrieve real-time price data
Access order book information
Get historical pricing data
Monitor funding rates for perpetual contracts

📉 Funding Rates Monitoring¶

Track funding rates across perpetual exchanges
Identify arbitrage opportunities
Monitor funding rate changes over time

Architecture¶

graph TB
    subgraph "AI Assistants"
        CLAUDE[Claude CLI]
        GEMINI[Gemini CLI]
    end

    subgraph "MCP Server"
        MCP[Hummingbot<br/>MCP Server]
    end

    subgraph "Hummingbot Infrastructure" 
        API[Hummingbot API<br/>Server]
        BOTS[Trading Bots]
    end

    subgraph "Exchanges"
        EX[Binance, OKX,<br/>Hyperliquid, etc.]
    end

    %% AI to MCP connections
    CLAUDE -->|MCP Protocol| MCP
    GEMINI -->|MCP Protocol| MCP

    %% MCP to Hummingbot API
    MCP -->|REST API| API

    %% API to infrastructure
    API <--> BOTS
    BOTS <--> EX
    API <--> EX

    %% Styling
    classDef aiStyle stroke:#5FFFD7,stroke-width:3px
    classDef mcpStyle stroke:#E549FF,stroke-width:3px  
    classDef hbStyle stroke:#00B1BB,stroke-width:3px

    class CLAUDE,GEMINI aiStyle
    class MCP mcpStyle
    class API,BOTS hbStyle

Getting Started¶

Ready to build AI trading agents with Hummingbot? Follow these steps:

Install the MCP Server - Set up development or production environment
Explore Available Tools - Learn about trading and portfolio management capabilities
Configure your AI assistant - Connect Claude, Gemini, or other MCP-compatible AI
Start trading conversations - Let AI manage your portfolio automatically

Quick Overview¶

The MCP server provides comprehensive trading capabilities through these tool categories:

🏦 Account & Portfolio Management¶

Monitor balances, track performance, and analyze portfolio allocation across all connected exchanges.

📊 Order & Position Management¶

Execute trades, manage orders, and control positions programmatically with AI oversight.

📈 Market Data & Analysis¶

Access real-time prices, funding rates, and order book data for informed decision making.

Usage with AI Assistants¶

Claude CLI¶

Install Claude CLI following Anthropic's guide

Configure MCP server in your Claude configuration:

{
  "mcpServers": {
    "hummingbot": {
      "command": "uv",
      "args": ["run", "mcp"],
      "cwd": "/path/to/hummingbot-mcp"
    }
  }
}

Start trading conversation:

You: Show me my portfolio balances across all exchanges
Claude: I'll check your portfolio balances using the Hummingbot MCP server...

Gemini CLI¶

Similar configuration process for Gemini CLI - refer to Google's documentation for MCP setup.

Example Workflows¶

Portfolio Analysis¶

AI: "What's my current portfolio worth and how is it distributed?"
MCP: Retrieves balances across all exchanges and calculates total value
AI: Provides detailed breakdown with recommendations

Automated Trading¶

AI: "Buy 0.1 BTC when the price drops below $45,000"
MCP: Monitors prices and executes order when conditions are met
AI: Confirms execution and provides trade summary

Risk Management¶

AI: "Close all positions with unrealized losses over 5%"
MCP: Analyzes open positions and closes those meeting criteria  
AI: Reports actions taken and updated portfolio status

Security Considerations¶

API Credentials: Store credentials securely and never commit them to version control
Network Access: Ensure MCP server can only be accessed by authorized AI assistants
Trading Limits: Set appropriate position sizes and risk limits in your strategies
Monitoring: Regularly monitor AI trading activity and set up alerts for unusual behavior

Development¶

Contributing¶

The Hummingbot MCP Server is open source. Contributions are welcome!

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Submit a pull request

Custom Tools¶

You can extend the MCP server by adding custom tools:

@mcp.tool()
async def my_custom_tool(parameter: str) -> str:
    """Custom tool description"""
    # Your implementation here
    return result