hummingbot

MCP Hummingbot Server

Claude と Gemini CLI が Hummingbot と連携し、複数の取引所で暗号資産の自動取引を行えるようにする MCP（Model Context Protocol）サーバーです。

インストールと設定

オプション 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：コンテナから localhost:8000 にアクセスできるように、--network host（下記参照）を使用します
   • 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=[[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: { }
   

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
   

サーバー設定

初回実行時に、サーバーは環境変数からデフォルト設定を作成します（環境変数がない場合は、デフォルトの認証情報を使用して 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 に保持されます

取引とアカウント管理

• アカウント管理とコネクターの設定
• ポートフォリオの残高と配分
• 注文の発注と管理
• ポジション管理
• 市場データ（価格、オーダーブック、ローソク足）
• 資金調達率
• ボットのデプロイと管理
• コントローラーの設定

開発

開発モードでサーバーを実行するには：

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 サーバーが起動していることを確認してください
   • 設定済みの URL で API にアクセスできることを確認してください

2. 認証情報が正しくない場合：

   • configure_server ツールを使用して、サーバーの認証情報を更新してください
   • または、.env ファイルの設定を確認してください

3. URL が正しくない場合：

   • configure_server ツールを使用して、サーバーの URL を更新してください
   • Mac/Windows の Docker では、localhost の代わりに host.docker.internal を使用してください

4. Docker のネットワークに問題がある場合：

   • Linux では、Docker の設定で --network host を使用してください
   • Mac/Windows では、API URL に host.docker.internal:8000 を使用してください

エラーの予防

MCP サーバーは次のように動作します：

• 認証エラー（401 エラー）の場合は再試行せず、認証情報が正しくないことをすぐに通知します
• 接続エラーの場合は再試行し、原因として考えられることをわかりやすく説明します
• Docker で実行しているかどうかを状況に応じて説明し、適切な解決方法を提案します
• 問題解決に適したツール（configure_server）を案内します