Servidor MCP de IBKR

Un servidor del Protocolo de Contexto de Modelos (MCP) que proporciona a los modelos de IA acceso seguro a los datos y funcionalidades de trading de Interactive Brokers (IBKR) a través de la API de TWS.

⚠️⚠️⚠️ Aviso legal ⚠️⚠️⚠️

Este software es para fines educativos y de desarrollo. Úselo bajo su propia responsabilidad. Los autores no se hacen responsables de ninguna pérdida financiera incurrida mediante el uso de este software. Pruebe siempre con trading en papel (paper trading) antes de usar dinero real.

Related MCP server: IBKR TWS MCP Server

🚀 Características

• Gestión de cuentas: Obtenga posiciones, detalles de cartera y resúmenes de cuenta

• Datos de mercado: Recupere datos históricos de precios e información de mercado en tiempo real

• Operaciones de trading: Coloque órdenes, gestione posiciones y realice un seguimiento de las ejecuciones

• Integración MCP: Integración fluida con modelos de IA que soportan el protocolo MCP

• CLI de ejecución única: Conexión-ejecución-desconexión por comando para scripts rápidos

• Lanzamiento automatizado de TWS (macOS): Un comando para iniciar TWS y rellenar automáticamente el 2FA TOTP

• Habilidad para Claude Code: Trading en lenguaje natural mediante la herramienta incluida skills/ibkr-trading

• Funciones de seguridad: Modo de solo lectura, restricciones de trading configurables y validación exhaustiva

• Alta disponibilidad: Reconexión automática, monitorización de latidos (heartbeat) y gestión elegante de errores

📋 Requisitos previos

• Python 3.10+

• Interactive Brokers TWS o IB Gateway

• Cuenta de IBKR activa (se recomienda trading en papel para pruebas)

🛠️ Instalación

1. Clonar el repositorio:

   git clone https://github.com/happy-shine/ibkr_mcp.git
   cd ibkr_mcp

2. Instalar dependencias:

   pip install -r requirements.txt

3. Configurar TWS/IB Gateway:

   • Habilite las conexiones API en la configuración de TWS/Gateway

   • Establezca el puerto del socket (predeterminado: 7497 para trading en papel, 7496 para real)

   • Configure las direcciones IP de confianza si es necesario

4. Configurar el servidor:

   cp config/config.yaml.example config/config.yaml
   # Edit config/config.yaml with your settings

🚀 Uso

Opción A: Servidor MCP

python run.py

El servidor hará lo siguiente:

1. Conectarse a TWS/IB Gateway

2. Iniciar el servidor MCP en el puerto configurado

3. Comenzar la monitorización de latidos

4. Registrar todas las actividades

Opción B: CLI de ejecución única

CLI ligera que se conecta por comando y sale; ideal para scripts de shell o consultas ad-hoc.

python cli.py positions
python cli.py summary
python cli.py quote AAPL
python cli.py history AAPL --duration "1 M" --bar "1 day"
python cli.py buy AAPL 10 --type MKT --confirm
python cli.py orders

Ejecute python cli.py --help para obtener la lista completa de comandos.

Nota sobre los datos de cotización: Si no tiene una suscripción de datos de mercado en tiempo real, quote recurre a la barra diaria más reciente mediante datos históricos (sin campos en tiempo real).

Opción C: Lanzamiento automatizado de TWS (solo macOS)

start_tws.py lanza TWS a través de IBC, detecta el diálogo de autenticación de segundo factor, genera un código TOTP con pyotp y lo escribe a través de AppleScript (osascript): inicio de sesión totalmente automatizado sin tocar el teclado.

python start_tws.py          # launch and auto-fill 2FA
python start_tws.py --wait   # also block until API port 7496 is listening

Requisitos (macOS):

Configuración:

1. Instale IBC siguiendo sus instrucciones para macOS (normalmente en ~/ibc/).

2. En ~/ibc/config.ini, establezca:

   • TradingMode=live (o paper)

   • SecondFactorDevice=Mobile Authenticator

   • Sus credenciales de IBKR

3. Guarde su secreto TOTP de IBKR (la cadena Base32 del código QR del autenticador) en ~/.ibkr-totp-secret o expórtelo como TOTP_SECRET.

4. Conceda permiso de Accesibilidad a Terminal (o a su lanzador de Python) en Ajustes del Sistema → Privacidad y Seguridad → Accesibilidad — necesario para que AppleScript interactúe con la ventana de TWS.

Nota de plataforma: start_tws.py depende de AppleScript/osascript y es solo para macOS. Los usuarios de Linux/Windows deberían usar IBC directamente o adaptar la capa de automatización de GUI (p. ej., xdotool en Linux, pywinauto en Windows).

Herramientas MCP disponibles

Herramientas de cuenta

• get_positions() - Obtener las posiciones actuales de la cuenta

• get_account_summary() - Obtener el saldo y las métricas de la cuenta

• get_portfolio() - Obtener información detallada de la cartera

Herramientas de datos de mercado

• get_historical_data(symbol, duration, bar_size) - Obtener datos históricos de precios

• get_market_data(symbol) - Obtener datos de mercado en tiempo real

• get_quote_from_history(symbol) - Última barra diaria como cotización (no se requiere suscripción)

• get_contract_details(symbol) - Obtener especificaciones del contrato

• get_option_chain - Obtener datos de opciones

Herramientas de trading

• place_order(symbol, action, quantity, order_type, ...) - Colocar órdenes de compra/venta

• get_orders(status) - Obtener historial y estado de las órdenes

• cancel_order(order_id) - Cancelar órdenes pendientes

• get_trades() - Obtener historial de ejecuciones

Ejemplos de interacciones con IA

AI: "What are my current positions?"
→ Calls get_positions() tool

AI: "Buy 100 shares of AAPL at market price"
→ Calls place_order(symbol="AAPL", action="BUY", quantity=100, order_type="MKT")

AI: "Show me AAPL's price history for the last week"
→ Calls get_historical_data(symbol="AAPL", duration="1 W", bar_size="1 day")

🤖 Habilidad para Claude Code

Una habilidad complementaria se encuentra en skills/ibkr-trading/SKILL.md. Permite a Claude Code enviar los comandos CLI anteriores desde instrucciones en lenguaje natural (p. ej., "muéstrame mis posiciones", "cotiza AAPL").

Para instalarla, cree un enlace simbólico en su directorio de habilidades de Claude Code:

ln -s "$(pwd)/skills/ibkr-trading" ~/.claude/skills/ibkr-trading

🔗 Enlaces relacionados y créditos

• API de TWS de Interactive Brokers — API oficial de Python (ibapi)

• IBC — Controlador de Interactive Brokers — Lanzador automático de TWS (usado por start_tws.py)

• pyotp — Biblioteca TOTP/HOTP (usada por start_tws.py)

• Especificación del Protocolo de Contexto de Modelos

• Framework FastMCP

• Claude Code — CLI de programación en pareja con IA que consume la habilidad incluida