drasticstatic working copy — Used by the Fortuna trading system. This is an independent repo created from a local clone of hummingbot/mcp. Upstream is tracked as a remote for voluntary comparison — changes are reviewed before applying.

# Check for upstream updates (review before applying)
git fetch upstream && git log upstream/main --oneline

👁 Docker Build
👁 Publish MCP

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=[emqx@node1.emqx.local]
    - 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:

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

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers

Tools

• configure_serverA
• explore_dex_poolsA
• explore_geckoterminalA
• get_market_dataA
• get_portfolio_overviewA
• manage_botsA
• manage_controllersA
• manage_executorsA