hummingbot

Name: hummingbot
Author: hummingbot

本地服务

github.com/hummingbot金融数据5931 周前更新

代码仓库

关于 hummingbot

MCP Hummingbot Server 是一个 MCP 服务，使 Claude 和 Gemini CLI 能够与 Hummingbot 交互，用于跨多个交易所的自动化加密货币交易。它面向需要通过 AI 管理交易机器人的用户，可通过 uv 或 Docker 运行。

主要功能

01通过 configure_server 工具查看和更新 API 连接
02账户与连接器配置、余额查询
03下单、仓位管理及市场数据获取
04资金费率查询与机器人部署管理
05支持 uv 本地运行与 Docker 部署

适用场景

01在 Claude Code 中查询多个交易所的账户余额
02通过 AI 客户端部署和管理交易机器人
03在云服务器上通过 Docker Compose 与 Hummingbot API 一起运行

MCP 相关

该项目是 MCP 服务，通过 stdio 向 Claude Code、Gemini CLI 等客户端提供与 Hummingbot API 交互的工具。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "hummingbot": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "HUMMINGBOT_API_URL",
        "-e",
        "HUMMINGBOT_USERNAME",
        "-e",
        "HUMMINGBOT_PASSWORD",
        "docker.io/hummingbot/hummingbot-mcp:0.1.0"
      ],
      "env": {
        "HUMMINGBOT_API_URL": "<HUMMINGBOT_API_URL>",
        "HUMMINGBOT_USERNAME": "<HUMMINGBOT_USERNAME>",
        "HUMMINGBOT_PASSWORD": "<HUMMINGBOT_PASSWORD>"
      }
    }
  }
}

启动命令

docker run -i --rm -e HUMMINGBOT_API_URL -e HUMMINGBOT_USERNAME -e HUMMINGBOT_PASSWORD docker.io/hummingbot/hummingbot-mcp:0.1.0

需要配置的环境变量

HUMMINGBOT_API_URLBase URL of the Hummingbot API (e.g., http://host.docker.internal:8820 or http://localhost:8000)

HUMMINGBOT_USERNAME密钥Hummingbot API username

HUMMINGBOT_PASSWORD密钥Hummingbot API password

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

ocidocker.io/hummingbot/hummingbot-mcp:0.1.0stdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

MCP Hummingbot Server

一个 MCP（Model Context Protocol）服务，可让 Claude 和 Gemini CLI 与 Hummingbot 交互，在多个交易所进行自动化加密货币交易。

安装与配置

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

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

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

克隆并安装依赖项：

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

创建 .env 文件：
```
cp .env.example .env
```

编辑 .env 文件，填写 Hummingbot API 凭据：

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

在 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（生产环境推荐）

创建 .env 文件：
```
touch .env
```
编辑 .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

拉取 Docker 镜像：

docker pull hummingbot/hummingbot-mcp:latest

在 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 服务运行在同一台服务器上：

创建 .env 文件：
```
touch .env
```

编辑 .env 文件，填写 Hummingbot API 凭据：

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

创建 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=[[email protected]]
      - 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: { }

部署：
```
docker compose up -d
```

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

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

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

docker ps

服务配置

首次运行时，服务会根据环境变量创建默认配置（或使用默认凭据连接到 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"
)

只有提供的参数会发生更改；未提供的参数将保留当前值。每次更新后，客户端都会自动重新连接。

环境变量

可在 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_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 等工具的引用

常见解决方案

API 未运行：
- 确保 Hummingbot API 服务正在运行
- 确认可以通过配置的 URL 访问 API
凭据错误：
- 使用 configure_server 工具更新服务凭据
- 或检查 .env 文件配置
URL 错误：
- 使用 configure_server 工具更新服务 URL
- 对于 Mac/Windows 上的 Docker，请使用 host.docker.internal，而不是 localhost
Docker 网络问题：
- 在 Linux 上，在 Docker 配置中使用 --network host
- 在 Mac/Windows 上，将 host.docker.internal:8000 用作 API URL

防止错误

MCP 服务将：

身份验证失败（401 错误）时不重试，而是立即告知你凭据有误
连接失败时重试，并提供有关可能问题的实用消息
提供上下文信息，说明你是否在 Docker 中运行，并建议相应的解决方案
引导你使用合适的工具（configure_server）来解决问题

支持 Markdown

登录后评论

基本信息

作者: hummingbot
版本: 0.1.0
传输方式: stdio
收录时间: 2025年10月6日
最近更新: 31 周前
官方 Registry: io.github.hummingbot/mcp

报告问题

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。