hummingbot_mcp 1.0.2

MCP server for Hummingbot API integration - manage crypto trading across multiple exchanges

MCP Hummingbot Server

An MCP (Model Context Protocol) server that enables Claude and Gemini CLI to interact with Hummingbot for automated cryptocurrency trading across multiple exchanges.

Installation & Configuration

Option 1: Using uv (Recommended for Development)

1. Install uv (if not already installed):

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

2. Clone and install dependencies:

   git clone https://github.com/hummingbot/mcp
   cd mcp
   uv sync
   

3. Create a .env file:

   cp .env.example .env
   

4. Edit the .env file with your Hummingbot API credentials:

   HUMMINGBOT_API_URL=http://localhost:8000
   HUMMINGBOT_USERNAME=admin
   HUMMINGBOT_PASSWORD=admin
   

5. Configure in Claude Code or Gemini CLI:

   {
     "mcpServers": {
       "hummingbot-mcp": {
         "type": "stdio",
         "command": "uv",
         "args": [
           "--directory",
           "/path/to/mcp",
           "run",
           "main.py"
         ]
       }
     }
   }
   

   Note: Make sure to replace /path/to/mcp with the actual path to your MCP directory.

Option 2: Using Docker (Recommended for Production)

1. Create a .env file:

   touch .env
   

2. Edit the .env file with your Hummingbot API credentials:

   HUMMINGBOT_API_URL=http://localhost:8000
   HUMMINGBOT_USERNAME=admin
   HUMMINGBOT_PASSWORD=admin
   

   Important: When running the MCP server in Docker and connecting to a Hummingbot API on your host:

   • Linux: Use --network host (see below) to allow the container to access localhost:8000
   • Mac/Windows: Change HUMMINGBOT_API_URL to http://host.docker.internal:8000

3. Pull the Docker image:

   docker pull hummingbot/hummingbot-mcp:latest
   

4. Configure in Claude Code or Gemini CLI:

   For Linux (using --network host):

   {
     "mcpServers": {
       "hummingbot-mcp": {
         "type": "stdio",
         "command": "docker",
         "args": [
           "run",
           "--rm",
           "-i",
           "--network",
           "host",
           "--env-file",
           "/path/to/mcp/.env",
           "-v",
           "$HOME/.hummingbot_mcp:/root/.hummingbot_mcp",
           "hummingbot/hummingbot-mcp:latest"
         ]
       }
     }
   }
   

   For Mac/Windows:

   {
     "mcpServers": {
       "hummingbot-mcp": {
         "type": "stdio",
         "command": "docker",
         "args": [
           "run",
           "--rm",
           "-i",
           "--env-file",
           "/path/to/mcp/.env",
           "-v",
           "$HOME/.hummingbot_mcp:/root/.hummingbot_mcp",
           "hummingbot/hummingbot-mcp:latest"
         ]
       }
     }
   }
   

   (Remember to set HUMMINGBOT_API_URL=http://host.docker.internal:8000 in your .env file)

   Note: Make sure to replace /path/to/mcp with the actual path to your MCP directory.

Cloud Deployment with Docker Compose

For cloud deployment where both Hummingbot API and MCP server run on the same server:

1. Create a .env file:

   touch .env
   

2. Edit the .env file with your Hummingbot API credentials:

   HUMMINGBOT_API_URL=http://localhost:8000
   HUMMINGBOT_USERNAME=admin
   HUMMINGBOT_PASSWORD=admin
   

3. Create a docker-compose.yml:

   services:
     hummingbot-api:
       container_name: hummingbot-api
       image: hummingbot/hummingbot-api:latest
       ports:
         - "8000:8000"
       volumes:
         - ./bots:/hummingbot-api/bots
         - /var/run/docker.sock:/var/run/docker.sock
       environment:
         - USERNAME=admin
         - PASSWORD=admin
         - BROKER_HOST=emqx
         - DATABASE_URL=postgresql+asyncpg://hbot:hummingbot-api@postgres:5432/hummingbot_api
       networks:
         - emqx-bridge
       depends_on:
         - postgres
   
     mcp-server:
       container_name: hummingbot-mcp
       image: hummingbot/hummingbot-mcp:latest
       stdin_open: true
       tty: true
       env_file:
         - .env
       environment:
         - HUMMINGBOT_API_URL=http://hummingbot-api:8000
       depends_on:
         - hummingbot-api
       networks:
         - emqx-bridge
   
     # Include other services from hummingbot-api docker-compose.yml as needed
     emqx:
       container_name: hummingbot-broker
       image: emqx:5
       restart: unless-stopped
       environment:
         - EMQX_NAME=emqx
         - EMQX_HOST=node1.emqx.local
         - EMQX_CLUSTER__DISCOVERY_STRATEGY=static
         - EMQX_CLUSTER__STATIC__SEEDS=[[e-mail]]
         - EMQX_LOADED_PLUGINS="emqx_recon,emqx_retainer,emqx_management,emqx_dashboard"
       volumes:
         - emqx-data:/opt/emqx/data
         - emqx-log:/opt/emqx/log
         - emqx-etc:/opt/emqx/etc
       ports:
         - "1883:1883"
         - "8883:8883"
         - "8083:8083"
         - "8084:8084"
         - "8081:8081"
         - "18083:18083"
         - "61613:61613"
       networks:
         emqx-bridge:
           aliases:
             - node1.emqx.local
       healthcheck:
         test: [ "CMD", "/opt/emqx/bin/emqx_ctl", "status" ]
         interval: 5s
         timeout: 25s
         retries: 5
   
     postgres:
       container_name: hummingbot-postgres
       image: postgres:15
       restart: unless-stopped
       environment:
         - POSTGRES_DB=hummingbot_api
         - POSTGRES_USER=hbot
         - POSTGRES_PASSWORD=hummingbot-api
       volumes:
         - postgres-data:/var/lib/postgresql/data
       ports:
         - "5432:5432"
       networks:
         - emqx-bridge
       healthcheck:
         test: ["CMD-SHELL", "pg_isready -U hbot -d hummingbot_api"]
         interval: 10s
         timeout: 5s
         retries: 5
   
   networks:
     emqx-bridge:
       driver: bridge
   
   volumes:
     emqx-data: { }
     emqx-log: { }
     emqx-etc: { }
     postgres-data: { }
   

4. Deploy:

   docker compose up -d
   

5. Configure in Claude Code or Gemini CLI to connect to existing container:

   {
     "mcpServers": {
       "hummingbot-mcp": {
         "type": "stdio",
         "command": "docker",
         "args": [
           "exec",
           "-i",
           "hummingbot-mcp",
           "uv",
           "run",
           "main.py"
         ]
       }
     }
   }
   

   Note: Replace hummingbot-mcp with your actual container name. You can find the container name by running:

   docker ps
   

Server Configuration

On first run, the server creates a default configuration from environment variables (or uses http://localhost:8000 with default credentials). Configuration is stored in ~/.hummingbot_mcp/server.yml.

Using the configure_server Tool

# Show the current server configuration
configure_server()

# Update the host and port
configure_server(host="192.168.1.100", port=8001)

# Update credentials
configure_server(username="admin", password="secure_password")

# Update everything at once
configure_server(
    name="production",
    host="prod-server",
    port=8000,
    username="admin",
    password="secure_password"
)

Only the provided parameters are changed; omitted ones keep their current values. The client automatically reconnects after any update.

Environment Variables

The following environment variables can be set in your .env file for the MCP server:

Variable	Default	Description
HUMMINGBOT_API_URL	http://localhost:8000	Initial default API server URL (used only on first run)
HUMMINGBOT_USERNAME	admin	Initial username (used only on first run)
HUMMINGBOT_PASSWORD	admin	Initial password (used only on first run)
HUMMINGBOT_TIMEOUT	30.0	Connection timeout in seconds
HUMMINGBOT_MAX_RETRIES	3	Maximum number of retry attempts
HUMMINGBOT_RETRY_DELAY	2.0	Delay between retries in seconds
HUMMINGBOT_LOG_LEVEL	INFO	Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)

Note: After initial setup, use the configure_server tool to update the server connection. Environment variables are only used to create the initial default configuration.

Requirements

• Python 3.11+
• Running Hummingbot API server
• Valid Hummingbot API credentials

Available Tools

The MCP server provides tools for:

Server Management

• configure_server: View or update the active Hummingbot API server connection
  • No parameters: show current server config
  • Any parameters: update and reconnect
  • Configuration persists in ~/.hummingbot_mcp/server.yml

Trading & Account Management

• Account management and connector setup
• Portfolio balances and distribution
• Order placement and management
• Position management
• Market data (prices, order books, candles)
• Funding rates
• Bot deployment and management
• Controller configuration

Development

To run the server in development mode:

uv run main.py

To run tests:

uv run pytest

Troubleshooting

The MCP server now provides comprehensive error messages to help diagnose connection and authentication issues:

Connection Errors

If you see error messages like:

• ❌ Cannot reach Hummingbot API at <url> - The API server is not running or not accessible
• ❌ Authentication failed when connecting to Hummingbot API - Incorrect username or password
• ❌ Failed to connect to Hummingbot API - Generic connection failure

The error messages will include:

• The exact URL being used
• Your configured username (password is masked)
• Specific suggestions on how to fix the issue
• References to tools like configure_server

Common Solutions

1. API Not Running:

   • Ensure your Hummingbot API server is running
   • Verify the API is accessible at the configured URL

2. Wrong Credentials:

   • Use configure_server tool to update server credentials
   • Or check your .env file configuration

3. Wrong URL:

   • Use configure_server tool to update the server URL
   • For Docker on Mac/Windows, use host.docker.internal instead of localhost

4. Docker Network Issues:

   • On Linux, use --network host in your Docker configuration
   • On Mac/Windows, use host.docker.internal:8000 as the API URL

Error Prevention

The MCP server will:

• Not retry on authentication failures (401 errors) - it will immediately tell you the credentials are wrong
• Retry on connection failures with helpful messages about what might be wrong
• Provide context about whether you're running in Docker and suggest appropriate fixes
• Guide you to the right tools (configure_server) to fix issues