Content
# 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):
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
2. **Clone and install dependencies**:
```bash
git clone https://github.com/hummingbot/mcp
cd mcp
uv sync
```
3. **Create a .env file**:
```bash
cp .env.example .env
```
4. **Edit the .env file** with your Hummingbot API credentials:
```env
HUMMINGBOT_API_URL=http://localhost:8000
HUMMINGBOT_USERNAME=admin
HUMMINGBOT_PASSWORD=admin
```
5. **Configure in Claude Code or Gemini CLI**:
```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)
1. **Create a .env file**:
```bash
touch .env
```
2. **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`
3. **Pull the Docker image**:
```bash
docker pull hummingbot/hummingbot-mcp:latest
```
4. **Configure in Claude Code or Gemini CLI**:
**For Linux (using --network host)**:
```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**:
```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:
1. **Create a .env file**:
```bash
touch .env
```
2. **Edit the .env file** with your Hummingbot API credentials:
```env
HUMMINGBOT_API_URL=http://localhost:8000
HUMMINGBOT_USERNAME=admin
HUMMINGBOT_PASSWORD=admin
```
3. **Create a docker-compose.yml**:
```yaml
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**:
```bash
docker compose up -d
```
5. **Configure in Claude Code or Gemini CLI to connect to existing container**:
```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:
```bash
docker ps
```
## Managing Multiple API Servers
The MCP server now supports managing multiple Hummingbot API servers. This is useful when you have multiple deployments or environments.
### Initial Setup
On first run, the server creates a default server from environment variables (or uses `http://localhost:8000` with default credentials). Configuration is stored in `~/.hummingbot_mcp/servers.yml`.
### Using the configure_api_servers Tool
```
# List all configured servers
configure_api_servers()
# Add a new server using full URL
configure_api_servers(
action="add",
name="production",
url="http://prod-server:8000",
username="admin",
password="secure_password"
)
# Add a server using just port (defaults to localhost)
configure_api_servers(
action="add",
name="local_8001",
port=8001,
username="admin",
password="secure_password"
)
# Add a server using default port 8000
configure_api_servers(
action="add",
name="local_default",
username="admin",
password="secure_password"
)
# Switch to a different server
configure_api_servers(action="set_default", name="production")
# Remove a server
configure_api_servers(action="remove", name="old_server")
```
All subsequent API calls will use the currently selected default server.
## 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_api_servers` tool to manage servers. Environment variables are only used to create the initial default server.
## Requirements
- Python 3.11+
- Running Hummingbot API server
- Valid Hummingbot API credentials
## Available Tools
The MCP server provides tools for:
### Server Management
- **configure_api_servers**: Manage multiple Hummingbot API server connections
- List all configured servers
- Add new servers with credentials
- Set default server (automatically reconnects client)
- Remove servers
- Configuration persists in `~/.hummingbot_mcp/servers.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_api_servers`
### 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_api_servers` tool to update server credentials
- Or check your `.env` file configuration
3. **Wrong URL**:
- Use `configure_api_servers` 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_api_servers`) to fix issues
Connection Info
You Might Also Like
MarkItDown MCP
Converting files and office documents to Markdown.
Time
Obtaining current time information and converting time between different...
Filesystem
Model Context Protocol Servers
Sequential Thinking
Offers a structured approach to dynamic and reflective problem-solving,...
Git
Model Context Protocol Servers
Context 7
Context7 MCP Server -- Up-to-date code documentation for LLMs and AI code editors