Hummingbot MCP Server Installation Guide¶

This guide shows you how to connect AI assistants to the Hummingbot API using the MCP (Model Context Protocol) server.

📋 Prerequisites¶

Before starting, ensure you have:

Hummingbot API Server running (Installation Guide)
Docker installed and running
API credentials (username/password from setup)
An AI Assistant - Claude Code, Gemini CLI, Codex CLI, or Claude Desktop

🚀 Install via CLI (Recommended)¶

The simplest way to connect AI assistants using command-line tools.

Claude Code¶

Claude Code is Anthropic's official CLI tool for using Claude in your terminal.

Quick Setup¶

Add the MCP server with one command:

claude mcp add --transport stdio hummingbot -- docker run --rm -i -e HUMMINGBOT_API_URL=http://host.docker.internal:8000 -v hummingbot_mcp:/root/.hummingbot_mcp hummingbot/hummingbot-mcp:latest

Local Hummingbot API URL

If you installed Hummingbot API from source and it's running locally outside of Docker, use http://localhost:8000 instead of http://host.docker.internal:8000

Start Trading¶

Use natural language in your terminal:

"Show me my portfolio balances"
"Create a market making strategy for ETH-USDT on Binance"
"What are my open positions?"
"Start Gateway in development mode for DEX trading"

Gemini CLI¶

gemini

Gemini CLI is Google's AI agent for your terminal.

Installation¶

Install Gemini CLI: Official Guide

Configuration¶

Navigate to config folder:
```
cd ~/.gemini
```
Edit settings.json:
```
nano settings.json
```

Add MCP server:

{
  "mcpServers": {
    "hummingbot": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "HUMMINGBOT_API_URL=http://host.docker.internal:8000",
        "-v", "hummingbot_mcp:/root/.hummingbot_mcp",
        "hummingbot/hummingbot-mcp:latest"
      ]
    }
  }
}

Verify connection:
```
gemini
/mcp list
```

✅ You should see hummingbot in the output.

Codex CLI¶

codex

Codex CLI is OpenAI's coding agent for developers.

Installation¶

Install Codex CLI: Official Guide

IDE Support

These instructions also work with Codex for VS Code and Cursor. See the IDE installation guide.

Configuration¶

Navigate to config folder:
```
cd ~/.codex
```
Edit config.toml:
```
nano config.toml
```

Add MCP server:

[mcp_servers.hummingbot]
command = "docker"
args = [
  "run",
  "--rm",
  "-i",
  "-e", "HUMMINGBOT_API_URL=http://host.docker.internal:8000",
  "-v", "hummingbot_mcp:/root/.hummingbot_mcp",
  "hummingbot/hummingbot-mcp:latest"
]

Verify connection:
```
codex
/mcp
```

✅ Codex should detect the Hummingbot MCP server.

🖥️ Install via Docker MCP Catalog¶

For users who prefer a graphical interface, Docker Desktop provides a built-in MCP catalog.

Setup Steps¶

Open Docker Desktop → MCP Toolkit → Catalog
Search for Hummingbot MCP Server and click ➕ Install
Go to the Configuration tab
Set environment variables:

Variable	Value
`HUMMINGBOT_API_URL`	`http://host.docker.internal:8000`
`HUMMINGBOT_API_USERNAME`	`admin` (or your username)
`HUMMINGBOT_API_PASSWORD`	`admin` (or your password)

Click the checkbox to save

Connect a Client¶

Go to MCP Toolkit → Clients
Choose your AI client (Claude Desktop, Cursor, VS Code)
Click Connect

Manual Connection (Alternative)¶

For clients not listed, add manually to your client config:

{
  "mcp": {
    "servers": {
      "hummingbot": {
        "command": "docker",
        "args": ["mcp", "gateway", "run"],
        "type": "stdio"
      }
    }
  }
}

✅ Testing Your Setup¶

Once configured, test with these commands:

"Show me my portfolio balances"
"List all active trading bots"
"Get the current BTC-USDT price on Binance"
"What's my total portfolio value?"

🐛 Troubleshooting¶

Connection Issues¶

Problem: MCP server won't connect

Solutions:

Ensure Hummingbot API is running: docker ps | grep hummingbot-api
Use http://host.docker.internal:8000 not http://localhost:8000 for local setups
Verify Docker is running

Authentication Errors¶

Problem: "Invalid credentials" or similar errors

Solutions:

Check username/password in .env file
Ensure credentials match what you configured during setup
Verify API is accessible: curl -u admin:admin http://localhost:8000/

Docker Issues¶

Problem: Docker-related errors

Solutions:

Restart Docker Desktop
Check Docker has network access
On Linux, ensure user is in docker group

🚀 Next Steps¶

After successful installation:

Explore Tools: See MCP Tools for available capabilities
Try Examples: Review Example Workflows
Security: Read Security Guidelines