MCP

🚀 MCP Hummingbot 服务器

MCP（模型上下文协议）服务器允许 Claude 和 Gemini CLI 与 Hummingbot 交互，实现跨多个交易所的自动化加密货币交易。

🚀 快速开始

MCP Hummingbot 服务器是一个强大的工具，可让 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. 使用你的 Hummingbot API 凭证编辑 .env 文件：

   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. 使用你的 Hummingbot API 凭证编辑 .env 文件：

   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. 使用你的 Hummingbot API 凭证编辑 .env 文件：

   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
   
     # 按需包含 hummingbot-api docker-compose.yml 中的其他服务
     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
   

✨ 主要特性

• 多服务器管理：支持管理多个 Hummingbot API 服务器，适用于多个部署或环境。
• 丰富的工具集：提供服务器管理、交易与账户管理等多种工具。
• 详细的错误信息：提供全面的错误消息，帮助诊断连接和认证问题。

💻 使用示例

管理多个 API 服务器

初始设置

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

使用 configure_api_servers 工具

# 列出所有已配置的服务器
configure_api_servers()

# 使用完整 URL 添加一个新服务器
configure_api_servers(
    action="add",
    name="production",
    url="http://prod-server:8000",
    username="admin",
    password="secure_password"
)

# 仅使用端口添加一个服务器（默认为 localhost）
configure_api_servers(
    action="add",
    name="local_8001",
    port=8001,
    username="admin",
    password="secure_password"
)

# 使用默认端口 8000 添加一个服务器
configure_api_servers(
    action="add",
    name="local_default",
    username="admin",
    password="secure_password"
)

# 切换到不同的服务器
configure_api_servers(action="set_default", name="production")

# 删除一个服务器
configure_api_servers(action="remove", name="old_server")

所有后续的 API 调用将使用当前选定的默认服务器。

开发环境运行

以开发模式运行服务器

uv run main.py

运行测试

uv run pytest

📚 详细文档

环境变量

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

⚠️ 重要提示 初始设置完成后，请使用 configure_api_servers 工具管理服务器。环境变量仅用于创建初始默认服务器。

要求

• Python 3.11+
• 正在运行的 Hummingbot API 服务器
• 有效的 Hummingbot API 凭证

可用工具

服务器管理

• configure_api_servers：管理多个 Hummingbot API 服务器连接
  • 列出所有已配置的服务器
  • 使用凭证添加新服务器
  • 设置默认服务器（自动重新连接客户端）
  • 删除服务器
  • 配置信息持久化存储在 ~/.hummingbot_mcp/servers.yml 中

交易与账户管理

• 账户管理和连接器设置
• 投资组合余额和分布
• 订单下单和管理
• 仓位管理
• 市场数据（价格、订单簿、K线）
• 资金费率
• 机器人部署和管理
• 控制器配置

故障排除

连接错误

如果你看到以下错误消息：

• ❌ Cannot reach Hummingbot API at <url> - API 服务器未运行或无法访问
• ❌ Authentication failed when connecting to Hummingbot API - 用户名或密码错误
• ❌ Failed to connect to Hummingbot API - 通用连接失败

错误消息将包含：

• 正在使用的准确 URL
• 你配置的用户名（密码会被屏蔽）
• 关于如何解决问题的具体建议
• 对 configure_api_servers 等工具的引用

常见解决方案

1. API 未运行：

   • 确保你的 Hummingbot API 服务器正在运行
   • 验证 API 是否可以在配置的 URL 上访问

2. 凭证错误：

   • 使用 configure_api_servers 工具更新服务器凭证
   • 或者检查你的 .env 文件配置

3. URL 错误：

   • 使用 configure_api_servers 工具更新服务器 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_api_servers）来解决问题