Hummingbot 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

1. Clone and install dependencies:

   git clone https://github.com/hummingbot/mcp

cd mcp uv sync

1. Create a .env file:

   cp .env.example .env

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

   HUMMINGBOT_API_URL=http://localhost:8000

HUMMINGBOT_USERNAME=admin HUMMINGBOT_PASSWORD=admin

1. 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

1. 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

1. Pull the Docker image:

   docker pull hummingbot/hummingbot-mcp:latest

1. 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

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

   HUMMINGBOT_API_URL=http://localhost:8000

HUMMINGBOT_USERNAME=admin HUMMINGBOT_PASSWORD=admin

1. 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_CLUSTERSTATICSEEDS=[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: { }

1. Deploy:

   docker compose up -d

1. 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 - 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

1. Wrong Credentials:

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

1. Wrong URL:

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

1. 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