MCP Hummingbot Server

An MCP server lets Claude and Gemini CLI interact with Hummingbot for automated cryptocurrency trading across multiple exchanges. It acts as a bridge between your preferred MCP clients and Hummingbot, enabling centralized management of connections and trading actions.

How to use

You use the MCP server by connecting your MCP client (such as Claude or Gemini CLI) to an MCP endpoint that points to your Hummingbot API. You can manage multiple Hummingbot API servers, switch the default server, and perform trading, portfolio, and bot-control actions through the MCP server. Start by configuring one or more servers, then direct your MCP client to the chosen server configuration. The server handles authentication, session management, and request routing to Hummingbot.

How to install

Prerequisites you need before installation are Python 3.11+ and a running Hummingbot API server.

Option 1: Using uv (Recommended for Development) follows these steps.

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

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

cp .env.example .env

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

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

Note: Replace /path/to/mcp with the actual path to your MCP directory.

## Option 2: Using Docker (Recommended for Production)

Follow these steps to run the MCP server in Docker.

Create a .env file and populate it with your Hummingbot API credentials:

touch .env

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

When running the MCP server in Docker and connecting to a Hummingbot API on your host, use the following guidance:

• Linux: use --network host to allow the container to access localhost:8000.
• Mac/Windows: set HUMMINGBOT_API_URL to http://host.docker.internal:8000.

## Configure in Claude Code or Gemini CLI

Docker-based runtimes require you to run the container with the proper environment and volumes. Use the commands shown below to connect the MCP client to the Docker container running the MCP server.

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

Note: 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, you can use a multi-service setup with Docker Compose.

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

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

docker compose up -d

Configure in Claude Code or Gemini CLI to connect to existing container using an exec-based run, for example:

{
  "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 it by running docker ps.

## Managing Multiple API Servers

The MCP server supports managing multiple Hummingbot API servers. This is useful when you have multiple deployments or environments. The default server is created on first run and configuration is stored at `~/.hummingbot_mcp/servers.yml`.

## Environment variables

Configure the following environment variables in your `.env` file for the MCP server. They form the initial default server on first run and can be managed later using the configure\_api\_servers tool.

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

```text
HUMMINGBOT_TIMEOUT=30.0
HUMMINGBOT_MAX_RETRIES=3
HUMMINGBOT_RETRY_DELAY=2.0
HUMMINGBOT_LOG_LEVEL=INFO

Environment variables list

The MCP server uses and can manage these environment variables for the initial setup and operation.

Environment variables used by configuration tools

After initial setup, manage your servers with the configure_api_servers tool instead of editing environment variables directly.

Additional configuration notes

If you are running in Docker on Mac or Windows, use host.docker.internal for the API URL when connecting to a host Hummingbot API. If you are running on Linux with Docker, prefer --network host to allow the container to access the host API. Ensure the API URL, username, and password match the running Hummingbot API instance.

Troubleshooting

The MCP server provides clear error messages for authentication and connection issues. Common problems include an unreachable API, invalid credentials, or incorrect URLs. The server will not retry on authentication failures but will retry on connectivity issues with guidance to fix the problem. Use the configure_api_servers tool to update credentials or URLs when needed.

Development

To run the server in development mode, start it with the development runner and run tests with the test harness.

uv run main.py

uv run pytest

Available tools

configure_api_servers

Manage multiple Hummingbot API server connections including listing, adding, setting default, and removing servers.

Account management

Manage trading accounts and connector setup for Hummingbot deployments.

Portfolio balances

View and distribute portfolio balances across connected accounts.

Order placement

Place and manage trading orders through the MCP server.

Position management

Monitor and control open trading positions.

Market data

Access prices, order books, and candles from connected exchanges.

Funding rates

Retrieve funding rate information for applicable markets.

Bot deployment

Deploy and manage trading bots via MCP integration.

Controller configuration

Configure controller behavior for automated trading workflows.