Copia de trabajo de drasticstatic — Utilizada por el sistema de trading Fortuna. Este es un repositorio independiente creado a partir de un clon local de hummingbot/mcp. El upstream se rastrea como un remoto para comparación voluntaria; los cambios se revisan antes de aplicarse.

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

Servidor MCP de Hummingbot

Un servidor MCP (Model Context Protocol) que permite a Claude y Gemini CLI interactuar con Hummingbot para el trading automatizado de criptomonedas en múltiples exchanges.

Instalación y configuración

Opción 1: Usando uv (Recomendado para desarrollo)

1. Instalar uv (si no está instalado):

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

2. Clonar e instalar dependencias:

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

3. Crear un archivo .env:

   cp .env.example .env

4. Editar el archivo .env con tus credenciales de la API de Hummingbot:

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

5. Configurar en Claude Code o Gemini CLI:

   {
     "mcpServers": {
       "hummingbot-mcp": {
         "type": "stdio",
         "command": "uv",
         "args": [
           "--directory",
           "/path/to/mcp",
           "run",
           "main.py"
         ]
       }
     }
   }

   Nota: Asegúrate de reemplazar /path/to/mcp con la ruta real a tu directorio MCP.

Opción 2: Usando Docker (Recomendado para producción)

1. Crear un archivo .env:

   touch .env

2. Editar el archivo .env con tus credenciales de la API de Hummingbot:

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

   Importante: Al ejecutar el servidor MCP en Docker y conectarse a una API de Hummingbot en tu host:

   • Linux: Usa --network host (ver abajo) para permitir que el contenedor acceda a localhost:8000

   • Mac/Windows: Cambia HUMMINGBOT_API_URL a http://host.docker.internal:8000

3. Descargar la imagen de Docker:

   docker pull hummingbot/hummingbot-mcp:latest

4. Configurar en Claude Code o Gemini CLI:

   Para Linux (usando --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"
         ]
       }
     }
   }

   Para 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"
         ]
       }
     }
   }

   (Recuerda establecer HUMMINGBOT_API_URL=http://host.docker.internal:8000 en tu archivo .env)

   Nota: Asegúrate de reemplazar /path/to/mcp con la ruta real a tu directorio MCP.

Despliegue en la nube con Docker Compose

Para despliegue en la nube donde tanto la API de Hummingbot como el servidor MCP se ejecutan en el mismo servidor:

1. Crear un archivo .env:

   touch .env

2. Editar el archivo .env con tus credenciales de la API de Hummingbot:

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

3. Crear un 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. Desplegar:

   docker compose up -d

5. Configurar en Claude Code o Gemini CLI para conectar al contenedor existente:

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

   Nota: Reemplaza hummingbot-mcp con el nombre real de tu contenedor. Puedes encontrar el nombre del contenedor ejecutando:

   docker ps

Related MCP server: ai-trader

Configuración del servidor

En la primera ejecución, el servidor crea una configuración predeterminada a partir de las variables de entorno (o usa http://localhost:8000 con credenciales predeterminadas). La configuración se almacena en ~/.hummingbot_mcp/server.yml.

Usando la herramienta 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"
)

Solo se cambian los parámetros proporcionados; los omitidos mantienen sus valores actuales. El cliente se reconecta automáticamente después de cualquier actualización.

Variables de entorno

Las siguientes variables de entorno se pueden establecer en tu archivo .env para el servidor MCP:

Nota: Después de la configuración inicial, usa la herramienta configure_server para actualizar la conexión del servidor. Las variables de entorno solo se usan para crear la configuración predeterminada inicial.

Requisitos

• Python 3.11+

• Servidor API de Hummingbot en ejecución

• Credenciales válidas de la API de Hummingbot

Herramientas disponibles

El servidor MCP proporciona herramientas para:

Gestión del servidor

• configure_server: Ver o actualizar la conexión activa al servidor API de Hummingbot

  • Sin parámetros: muestra la configuración actual del servidor

  • Con parámetros: actualiza y reconecta

  • La configuración persiste en ~/.hummingbot_mcp/server.yml

Gestión de trading y cuentas

• Gestión de cuentas y configuración de conectores

• Saldos de cartera y distribución

• Colocación y gestión de órdenes

• Gestión de posiciones

• Datos de mercado (precios, libros de órdenes, velas)

• Tasas de financiación

• Despliegue y gestión de bots

• Configuración del controlador

Desarrollo

Para ejecutar el servidor en modo de desarrollo:

uv run main.py

Para ejecutar pruebas:

uv run pytest

Solución de problemas

El servidor MCP ahora proporciona mensajes de error completos para ayudar a diagnosticar problemas de conexión y autenticación:

Errores de conexión

Si ves mensajes de error como:

• ❌ Cannot reach Hummingbot API at <url> - El servidor API no se está ejecutando o no es accesible

• ❌ Authentication failed when connecting to Hummingbot API - Nombre de usuario o contraseña incorrectos

• ❌ Failed to connect to Hummingbot API - Fallo de conexión genérico

Los mensajes de error incluirán:

• La URL exacta que se está utilizando

• Tu nombre de usuario configurado (la contraseña está enmascarada)

• Sugerencias específicas sobre cómo solucionar el problema

• Referencias a herramientas como configure_server

Soluciones comunes

1. API no ejecutándose:

   • Asegúrate de que tu servidor API de Hummingbot esté en ejecución

   • Verifica que la API sea accesible en la URL configurada

2. Credenciales incorrectas:

   • Usa la herramienta configure_server para actualizar las credenciales del servidor

   • O verifica la configuración de tu archivo .env

3. URL incorrecta:

   • Usa la herramienta configure_server para actualizar la URL del servidor

   • Para Docker en Mac/Windows, usa host.docker.internal en lugar de localhost

4. Problemas de red de Docker:

   • En Linux, usa --network host en tu configuración de Docker

   • En Mac/Windows, usa host.docker.internal:8000 como la URL de la API

Prevención de errores

El servidor MCP:

• No reintentará en fallos de autenticación (errores 401): te dirá inmediatamente que las credenciales son incorrectas

• Reintentará en fallos de conexión con mensajes útiles sobre qué podría estar mal

• Proporcionará contexto sobre si estás ejecutando en Docker y sugerirá correcciones apropiadas

• Te guiará a las herramientas correctas (configure_server) para solucionar problemas