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)

Install uv (if not already installed):

Terminal

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

Clone and install dependencies:

bash

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

Create a .env file:
bash
```
cp .env.example .env
```

Edit the .env file with your Hummingbot API credentials:

env

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

Configure in Claude Code or Gemini CLI:

config.json

{
  "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)

Create a .env file:
bash
```
touch .env
```
Edit the .env file with your Hummingbot API credentials:
env
```
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

Pull the Docker image:

Terminal

docker pull hummingbot/hummingbot-mcp:latest

Configure in Claude Code or Gemini CLI:

For Linux (using --network host):

config.json

{
  "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:

config.json

{
  "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:

Create a .env file:
bash
```
touch .env
```

Edit the .env file with your Hummingbot API credentials:

env

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

Create a docker-compose.yml:

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: { }

Deploy:
Terminal
```
docker compose up -d
```

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

config.json

{
  "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:

Terminal

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

Code

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

bash

uv run main.py

To run tests:

bash

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

API Not Running:
- Ensure your Hummingbot API server is running
- Verify the API is accessible at the configured URL
Wrong Credentials:
- Use configure_server tool to update server credentials
- Or check your .env file configuration
Wrong URL:
- Use configure_server tool to update the server URL
- For Docker on Mac/Windows, use host.docker.internal instead of localhost
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