drasticstatic 작업 복사본 — Fortuna 트레이딩 시스템에서 사용됩니다. 이 저장소는 hummingbot/mcp의 로컬 복제본에서 생성된 독립적인 저장소입니다. 업스트림은 자발적인 비교를 위해 원격으로 추적되며, 변경 사항은 적용하기 전에 검토됩니다.

# Check for upstream updates (review before applying)
git fetch upstream && git log upstream/main --oneline

MCP Hummingbot 서버

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=[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

Related MCP server: ai-trader

서버 구성

처음 실행 시 서버는 환경 변수에서 기본 구성을 생성합니다(또는 기본 자격 증명과 함께 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 파일에 다음 환경 변수를 설정할 수 있습니다:

참고: 초기 설정 후 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)로 안내합니다.