IBKR MCP

Servidor MCP de Interactive Brokers

AVISO LEGAL: Este es un servidor MCP no oficial, desarrollado por la comunidad y NO está afiliado ni respaldado por Interactive Brokers. Este software se encuentra en estado Alpha y puede no funcionar perfectamente.

Un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona integración con la plataforma de trading de Interactive Brokers. Este servidor permite a los asistentes de IA interactuar con tu cuenta de IB para recuperar datos de mercado, consultar posiciones y realizar operaciones.

🔒 Aviso de Seguridad

Características

• Integración con la API de Interactive Brokers: Capacidades completas de trading, incluyendo gestión de cuentas, seguimiento de posiciones, datos de mercado en tiempo real y gestión de órdenes (órdenes de mercado, límite y stop)
• Soporte para Flex Query: Ejecuta Flex Queries para recuperar estados de cuenta, confirmaciones de operaciones y datos históricos. Las consultas se recuerdan automáticamente para facilitar su reutilización
• Autenticación flexible: Elige entre autenticación OAuth basada en navegador o modo headless con credenciales para entornos automatizados, incluida la anulación totalmente automatizada de 2FA con TOTP. Consulta el Documento de Estrategia TOTP 2FA para obtener una configuración detallada y advertencias de riesgo importantes.
• Configuración sencilla: Ejecuta directamente con npx - no se requiere Docker ni instalaciones adicionales. Incluye IB Gateway preconfigurado y runtime de Java para todas las plataformas

Aviso de Seguridad

ADVERTENCIAS IMPORTANTES:

• Riesgo financiero: El trading implica un riesgo sustancial de pérdida. Siempre prueba primero con trading en papel.
• Seguridad: Este software maneja datos financieros sensibles. Ejecútalo solo localmente, nunca en servidores públicos.
• Sin garantía: Este software no oficial no ofrece garantías. Úsalo bajo tu propio riesgo.
• No es asesoramiento financiero: Esta herramienta es solo para automatización, no constituye asesoramiento financiero.

Requisitos previos

No se requieren instalaciones adicionales para plataformas principales. Este paquete incluye:

• IB Gateway preconfigurado para todas las plataformas (Linux, macOS, Windows)
• Entorno de ejecución de Java (JRE) para macOS, Windows y builds estándar de Linux
• Descarga automática de JRE musl en el primer inicio para contenedores basados en Alpine (p. ej. node:lts-alpine, supergateway)
• Todas las dependencias necesarias

Solo necesitas:

• Cuenta de Interactive Brokers (trading en papel o real)
• Node.js 18+ (para ejecutar el servidor MCP)

Inicio rápido

Añade este servidor MCP a tu configuración de Cursor/Claude:

{
  "mcpServers": {
    "interactive-brokers": {
      "command": "npx",
      "args": ["-y", "interactive-brokers-mcp"]
    }
  }
}

Cuando uses el servidor por primera vez, se abrirá automáticamente una ventana del navegador para el flujo de autenticación OAuth de Interactive Brokers. Inicia sesión con tus credenciales de IB para autorizar la conexión.

Configuración del modo Headless

Para entornos automatizados o si prefieres no usar un navegador para la autenticación, puedes habilitar el modo headless configurándolo en tu configuración del servidor MCP:

{
  "mcpServers": {
    "interactive-brokers": {
      "command": "npx",
      "args": ["-y", "interactive-brokers-mcp"],
      "env": {
        "IB_HEADLESS_MODE": "true",
        "IB_USERNAME": "your_ib_username",
        "IB_PASSWORD_AUTH": "your_ib_password"
      }
    }
  }
}

En modo headless, el servidor se autenticará automáticamente usando tus credenciales sin abrir una ventana del navegador. Esto es útil para:

• Sistemas de trading automatizados
• Entornos de servidor sin pantalla
• Pipelines de CI/CD
• Situaciones donde no se desea interacción con el navegador

Importante: Incluso en modo headless, Interactive Brokers puede requerir autenticación de dos factores (2FA). Cuando se activa 2FA, la autenticación headless esperará hasta 60 segundos para que completes el proceso de 2FA a través de tu método configurado (aplicación móvil, SMS, etc.) antes de devolver una respuesta AUTHENTICATION_PENDING. Espera a que se complete la aprobación y luego verifica la información de la cuenta nuevamente.

Para habilitar el trading en papel, añade "IB_PAPER_TRADING": "true" a tus variables de entorno:

{
  "mcpServers": {
    "interactive-brokers": {
      "command": "npx",
      "args": ["-y", "interactive-brokers-mcp"],
      "env": {
        "IB_HEADLESS_MODE": "true",
        "IB_USERNAME": "your_ib_username",
        "IB_PASSWORD_AUTH": "your_ib_password",
        "IB_PAPER_TRADING": "true"
      }
    }
  }
}

Nota de seguridad: Almacena las credenciales de forma segura y nunca las confirmes en el control de versiones. Considera usar archivos de variables de entorno o sistemas seguros de gestión de credenciales.

Configuración de Flex Query (Opcional)

Para usar Flex Queries y recuperar estados de cuenta y datos históricos, necesitas configurar tu Token del Servicio Web Flex:

{
  "mcpServers": {
    "interactive-brokers": {
      "command": "npx",
      "args": ["-y", "interactive-brokers-mcp"],
      "env": {
        "IB_FLEX_TOKEN": "your_flex_token_here"
      }
    }
  }
}

Cómo obtener tu Token Flex:

1. Inicia sesión en Gestión de Cuentas de Interactive Brokers
2. Ve a Configuración → Configuración de la cuenta
3. Navega a Informes → Servicio Web Flex
4. Genera o recupera tu Token del Servicio Web Flex

Para instrucciones detalladas sobre cómo habilitar el Servicio Web Flex, consulta la Guía del Servicio Web Flex de IB.

Creación de Flex Queries:

1. Ve a Informes → Flex Queries en Gestión de Cuentas
2. Crea o personaliza tu plantilla de consulta
3. Haz clic en el icono de información junto a tu consulta para encontrar su ID de consulta

Para una guía completa sobre cómo crear y personalizar Flex Queries, consulta la Guía de Flex Queries de IB.

Nota: Cuando ejecutas una Flex Query por primera vez, el servidor MCP la guarda automáticamente con su nombre de la API. Las ejecuciones futuras pueden referenciar la consulta por su ID o por su nombre guardado.

Características de Flex Query:

• Memoria automática: Cuando ejecutas una Flex Query, se guarda automáticamente para uso futuro
• Reutilización fácil: Las consultas utilizadas anteriormente se recuerdan - no es necesario copiar los IDs de consulta repetidamente
• Nombres amigables: Opcionalmente, proporciona un nombre amigable al ejecutar una consulta por primera vez
• Olvidar consultas: Elimina consultas que ya no necesites con la herramienta forget_flex_query

Variables de configuración

Característica	Variable de entorno	Argumento de línea de comandos
Nombre de usuario	IB_USERNAME	--ib-username
Contraseña	IB_PASSWORD_AUTH	--ib-password-auth
Modo headless	IB_HEADLESS_MODE	--ib-headless-mode
Trading en papel	IB_PAPER_TRADING	--ib-paper-trading
Tiempo de espera de autenticación	IB_AUTH_TIMEOUT	--ib-auth-timeout
Segundos de espera de autenticación	IB_AUTH_WAIT_SECONDS	--ib-auth-wait-seconds
Segundos de sondeo de autenticación	IB_AUTH_POLL_SECONDS	--ib-auth-poll-seconds
Forzar gateway empaquetado independiente	IB_FORCE_STANDALONE_GATEWAY	N/A
Token Flex	IB_FLEX_TOKEN	N/A
Modo solo lectura	IB_READ_ONLY_MODE	--ib-read-only-mode
Estrategia 2FA	IB_TWO_FA_STRATEGY	N/A
Clave secreta TOTP	IB_TOTP_SECRET	N/A
Anulaciones de selector de página de inicio de sesión	IB_SELECTOR_USERNAME, IB_SELECTOR_PASSWORD, IB_SELECTOR_LOGIN_SUBMIT	N/A
Anulaciones de selector de formulario TOTP	IB_SELECTOR_TOTP_INPUT, IB_SELECTOR_TOTP_SUBMIT	N/A

Consulta el Documento de Estrategia TOTP 2FA para obtener detalles sobre las variables de 2FA y anulación de selectores.

Ciclo de vida del Gateway

Al iniciar, el MCP primero sondea los endpoints locales del Gateway accesibles en el puerto configurado y en los puertos comunes del Client Portal Gateway. Si se encuentra un Gateway existente en buen estado, el MCP se conecta a él y no inicia otro Gateway empaquetado.

Cuando no hay un Gateway existente adecuado accesible, el MCP inicia el Gateway Java empaquetado como un proceso separado duradero. Los archivos de coordinación del runtime se almacenan en ib-gateway/.runtime/:

• gateway-session.json registra el pid, puerto, versión y rutas de registro del Gateway gestionado por MCP.
• gateway-session.lock evita que dos procesos MCP inicien Gateways gestionados duplicados al mismo tiempo.
• gateway.stdout.log y gateway.stderr.log reciben la salida del proceso del Gateway.

El cierre normal del MCP se desconecta del Gateway y lo deja en ejecución para que las ejecuciones posteriores del MCP puedan reutilizarlo. Si se establece IB_FORCE_STANDALONE_GATEWAY=true, el MCP omite la detección de Gateways externos no relacionados, pero aún reutiliza o coordina a través de los archivos de metadatos de sesión y bloqueo gestionados por MCP.

Para restablecer la sesión del Gateway gestionado, detén el proceso del Gateway registrado en ib-gateway/.runtime/gateway-session.json, luego elimina ib-gateway/.runtime/gateway-session.json y cualquier ib-gateway/.runtime/gateway-session.lock obsoleto. El MCP elimina automáticamente los metadatos obsoletos cuando el pid registrado ya no existe.

Herramientas MCP disponibles

Gestión de Trading y Cuentas

Herramienta	Descripción
get_account_info	Recupera información de la cuenta y saldos
get_positions	Obtiene posiciones actuales y P&L
get_market_data	Datos de mercado en tiempo real para símbolos
place_order	Coloca órdenes de mercado, límite o stop (solo si el modo de solo lectura está deshabilitado)
get_order_status	Verifica el estado de ejecución de órdenes
get_live_orders	Obtiene todas las órdenes activas/abiertas para monitoreo

Flex Queries (Requiere IB_FLEX_TOKEN)

Herramienta	Descripción
get_flex_query	Ejecuta una Flex Query y recupera estados de cuenta (se guarda automáticamente para reutilizar)
list_flex_queries	Lista todas las Flex Queries utilizadas anteriormente
forget_flex_query	Elimina una Flex Query guardada de la memoria

Solución de problemas

Problemas de autenticación:

• Usa la interfaz web que se abre automáticamente
• Completa cualquier autenticación de dos factores requerida
• Prueba el modo de trading en papel si el trading real falla

Problemas de detección del Gateway:

• Si otro IB Gateway ya está escuchando en un puerto local pero no debería reutilizarse, establece IB_FORCE_STANDALONE_GATEWAY=true
• Los Gateways existentes solo se reutilizan cuando el proceso MCP puede alcanzarlos a través de HTTPS; de lo contrario, se inicia el gateway independiente empaquetado en un puerto disponible
• Para problemas de inicio del Gateway gestionado por MCP, inspecciona ib-gateway/.runtime/gateway.stdout.log, ib-gateway/.runtime/gateway.stderr.log y ib-gateway/.runtime/gateway-session.json
• Para limpiar un bloqueo de inicio gestionado obsoleto, confirma que ningún proceso MCP esté iniciando actualmente el Gateway y luego elimina ib-gateway/.runtime/gateway-session.lock

Soporte

• Este servidor: Abre un issue en este repositorio.

Licencia

Licencia MIT - consulta el archivo LICENSE para obtener más detalles.

Agradecimientos a nuestros colaboradores

Un gran agradecimiento a todos los que han contribuido a mejorar este proyecto.