shield_lock
金大哥
← 返回 MCP 目录
public公开dns本地运行

mcp

一个MCP协议服务器，允许Claude和Gemini CLI通过Hummingbot API与多个加密货币交易所进行自动化交易交互，支持多服务器管理和Docker部署。

article

README

🚀 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 文件中设置： | 属性 | 详情 | |------|------| | HUMMINGBOT_API_URL | http://localhost:8000 | 初始默认 API 服务器 URL（仅在首次运行时使用） | | HUMMINGBOT_USERNAME | admin | 初始用户名（仅在首次运行时使用） | | HUMMINGBOT_PASSWORD | admin | 初始密码（仅在首次运行时使用） | | HUMMINGBOT_TIMEOUT | 30.0 | 连接超时时间（秒） | | HUMMINGBOT_MAX_RETRIES | 3 | 最大重试次数 | | HUMMINGBOT_RETRY_DELAY | 2.0 | 重试间隔时间（秒） | | HUMMINGBOT_LOG_LEVEL | INFO | 日志级别（DEBUG、INFO、WARNING、ERROR、CRITICAL） |

⚠️ 重要提示 初始设置完成后，请使用 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）来解决问题
help

运行方式说明

cloud

托管运行

托管运行通常表示这个 MCP Server 由服务方环境承载，用户一般按页面提供的连接方式或授权流程接入，不需要在本地长期启动一个 MCP 进程

  1. 打开服务方连接页
  2. 完成授权或复制端点
  3. 在 MCP 客户端中连接
terminal

本地运行 / 其它方式

本地运行通常需要用户在自己的电脑或服务器上安装依赖，把 server_config 复制到 MCP 客户端，并按 env_schema 补齐环境变量、密钥或其它配置

  1. 复制 server_config
  2. 安装所需依赖
  3. 补齐环境变量后重启客户端