drasticstatic 工作副本 — 由 Fortuna 交易系统 使用。这是一个从 hummingbot/mcp 本地克隆创建的独立仓库。上游仓库被跟踪为远程仓库以供自愿比较 — 更改在应用前会经过审查。

# Check for upstream updates (review before applying)
git fetch upstream && git log upstream/main --oneline

MCP Hummingbot 服务器

一个 MCP（模型上下文协议）服务器，使 Claude 和 Gemini CLI 能够与 Hummingbot 交互，从而在多个交易所进行自动化加密货币交易。

安装与配置

选项 1：使用 uv（推荐用于开发）

1. 安装 uv（如果尚未安装）：

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

2. 克隆并安装依赖项：

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

3. 创建 .env 文件：

   cp .env.example .env

4. 编辑 .env 文件，填入您的 Hummingbot API 凭据：

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

5. 在 Claude Code 或 Gemini CLI 中配置：

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

   注意：请确保将 /path/to/mcp 替换为您 MCP 目录的实际路径。

选项 2：使用 Docker（推荐用于生产）

1. 创建 .env 文件：

   touch .env

2. 编辑 .env 文件，填入您的 Hummingbot API 凭据：

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

   重要：在 Docker 中运行 MCP 服务器并连接到宿主机上的 Hummingbot API 时：

   • Linux：使用 --network host（见下文）以允许容器访问 localhost:8000

   • Mac/Windows：将 HUMMINGBOT_API_URL 更改为 http://host.docker.internal:8000

3. 拉取 Docker 镜像：

   docker pull hummingbot/hummingbot-mcp:latest

4. 在 Claude Code 或 Gemini CLI 中配置：

   对于 Linux（使用 --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"
         ]
       }
     }
   }

   对于 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"
         ]
       }
     }
   }

   （记得在您的 .env 文件中设置 HUMMINGBOT_API_URL=http://host.docker.internal:8000）

   注意：请确保将 /path/to/mcp 替换为您 MCP 目录的实际路径。

使用 Docker Compose 进行云部署

对于 Hummingbot API 和 MCP 服务器运行在同一服务器上的云部署：

1. 创建 .env 文件：

   touch .env

2. 编辑 .env 文件，填入您的 Hummingbot API 凭据：

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

3. 创建 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: { }

4. 部署：

   docker compose up -d

5. 在 Claude Code 或 Gemini CLI 中配置以连接到现有容器：

   {
     "mcpServers": {
       "hummingbot-mcp": {
         "type": "stdio",
         "command": "docker",
         "args": [
           "exec",
           "-i",
           "hummingbot-mcp",
           "uv",
           "run",
           "main.py"
         ]
       }
     }
   }

   注意：将 hummingbot-mcp 替换为您实际的容器名称。您可以通过运行以下命令找到容器名称：

   docker ps

Related MCP server: ai-trader

服务器配置

首次运行时，服务器会根据环境变量创建默认配置（或使用 http://localhost:8000 和默认凭据）。配置存储在 ~/.hummingbot_mcp/server.yml 中。

使用 configure_server 工具

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

仅更改提供的参数；省略的参数将保持其当前值。客户端在任何更新后都会自动重新连接。

环境变量

可以在您的 .env 文件中为 MCP 服务器设置以下环境变量：

注意：初始设置后，请使用 configure_server 工具更新服务器连接。环境变量仅用于创建初始默认配置。

要求

• Python 3.11+

• 正在运行的 Hummingbot API 服务器

• 有效的 Hummingbot API 凭据

可用工具

MCP 服务器提供以下工具：

服务器管理

• configure_server：查看或更新活动的 Hummingbot API 服务器连接

  • 无参数：显示当前服务器配置

  • 任何参数：更新并重新连接

  • 配置持久化存储在 ~/.hummingbot_mcp/server.yml 中

交易与账户管理

• 账户管理和连接器设置

• 投资组合余额和分布

• 订单下达和管理

• 持仓管理

• 市场数据（价格、订单簿、K 线）

• 资金费率

• 机器人部署和管理

• 控制器配置

开发

以开发模式运行服务器：

uv run main.py

运行测试：

uv run pytest

故障排除

MCP 服务器现在提供全面的错误消息，以帮助诊断连接和身份验证问题：

连接错误

如果您看到如下错误消息：

• ❌ Cannot reach Hummingbot API at <url> - API 服务器未运行或无法访问

• ❌ Authentication failed when connecting to Hummingbot API - 用户名或密码错误

• ❌ Failed to connect to Hummingbot API - 通用连接失败

错误消息将包含：

• 正在使用的确切 URL

• 您配置的用户名（密码已掩码）

• 关于如何解决问题的具体建议

• 指向 configure_server 等工具的参考

常见解决方案

1. API 未运行：

   • 确保您的 Hummingbot API 服务器正在运行

   • 验证 API 在配置的 URL 处是否可访问

2. 凭据错误：

   • 使用 configure_server 工具更新服务器凭据

   • 或检查您的 .env 文件配置

3. URL 错误：

   • 使用 configure_server 工具更新服务器 URL

   • 对于 Mac/Windows 上的 Docker，请使用 host.docker.internal 而不是 localhost

4. Docker 网络问题：

   • 在 Linux 上，在 Docker 配置中使用 --network host

   • 在 Mac/Windows 上，使用 host.docker.internal:8000 作为 API URL

错误预防

MCP 服务器将：

• 不会在身份验证失败（401 错误）时重试 - 它会立即告知您凭据错误

• 会在连接失败时重试，并提供有关可能出错原因的有用消息

• 提供上下文，说明您是否在 Docker 中运行，并建议适当的修复方法

• 引导您使用正确的工具 (configure_server) 来解决问题