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）來解決問題