Options ORB MCP System

Un sistema demo-first de servidores MCP que exponen herramientas de análisis de mercado, investigación, optimización y ejecución a un cliente LLM (Cursor / Claude Desktop). Opera spreads verticales de opciones de riesgo definido impulsados por una señal de ruptura de rango de apertura (ORB), optimizados por ventana de sesión (Asia / Londres / Nueva York), con estrictos controles de riesgo dimensionados para ~£1000 de capital.

Aviso de riesgo. Este es software educativo, no asesoramiento financiero. Operar con opciones conlleva riesgo de pérdida de capital. El sistema usa por defecto una cuenta de papel y se niega a colocar órdenes reales a menos que actives deliberadamente dos interruptores de seguridad independientes. «Rendimientos estables» es un objetivo de diseño, nunca una garantía.

Por qué el diseño tiene este aspecto

• Tu brief describía ORB, ventanas de sesión, SL/TP y MetaTrader. Las opciones reales (strikes/vencimientos/griegas) no viven en MT5, por lo que esto utiliza Interactive Brokers (API de papel + acceso al Reino Unido + opciones de EE. UU.).

• £1000 significa solo spreads de riesgo definido (verticales). La ruptura ORB en el subyacente es la señal direccional; el ejecutor coloca el spread.

• Las ventanas de sesión se replantean para opciones de EE. UU.: Asia = rango globex nocturno, Londres = UE/pre-market, Nueva York = el clásico ORB de apertura estadounidense.

Related MCP server: IBKR TWS MCP Server

Arquitectura

LLM client (Cursor / Claude)
      |  MCP (stdio)
      +-- market-data-mcp   (ORB signal, regime, option chain, IV)
      +-- research-mcp      (trade journal, performance, learning)
      +-- optimiser-mcp     (backtest, walk-forward, compare strategies)
      +-- execution-mcp     (preview/place spreads with bracket SL/TP)
                 |
              core/ library  <----  dashboard/ (read-only web GUI, port 8787)
                 |
        IB Gateway / TWS  (paper first)

Requisitos previos

1. Python 3.11+ (probado con 3.13).

2. Un entorno virtual con pip (pasos a continuación). uv se admite como alternativa opcional si lo tienes.

3. Una cuenta de Interactive Brokers con trading en papel habilitado, además de TWS o IB Gateway en ejecución con la API habilitada (Configure -> API -> Settings -> «Enable ActiveX and Socket Clients»).

   • Valores por defecto de papel: TWS 7497, IB Gateway 4002.

   • ¿Nuevo en esto? Sigue la guía de configuración de IBKR paso a paso (instala Gateway, inicia sesión en papel, habilita la API, datos en diferido gratuitos).

El trading en papel usa datos IBKR en vivo por defecto; los sintéticos/«Demo data» son solo una opción offline explícita. El backtester y las herramientas de valoración funcionan sin IBKR: solo los datos de mercado en vivo y la colocación de órdenes necesitan Gateway/TWS en ejecución. Las cuentas de papel obtienen datos en diferido gratuitos de 15 minutos, y el sistema recurre a ellos automáticamente cuando no tienes una suscripción en tiempo real.

Configuración

Ejecuta estos pasos desde la raíz del repositorio. Los comandos asumen que tu entorno virtual está activado (para que python/pytest resuelvan a .venv).

# 1. Create and activate a virtual environment
python -m venv .venv
.venv\Scripts\activate            # PowerShell / CMD
# source .venv/Scripts/activate   # Git Bash on Windows
# source .venv/bin/activate       # macOS / Linux

# 2. Install the project + dev tools (pytest, ruff)
pip install -e ".[dev]"

# 3. Configure
copy .env.example .env            # Windows;  Unix: cp .env.example .env
# then edit IBKR_PORT (IB Gateway paper = 4002, TWS paper = 7497)

# 4. Register the MCP servers with your client (writes .cursor/mcp.json)
python -m scripts.setup

# 5. Sanity check the tests (no IBKR needed)
pytest -q

# 6. Watch the whole loop run offline on synthetic data (no IBKR needed)
python -m scripts.demo

# 7. Open the GUI dashboard (historic trades, strategy used, live positions)
python -m dashboard.app           # then open http://127.0.0.1:8787

# (once IB Gateway is running) confirm the live connection + a sample quote
python -m scripts.check_ibkr

La demo ejercita cada agente de principio a fin: encuentra una ruptura ORB, dimensiona el riesgo de un spread de riesgo definido, simula una ejecución en papel, la registra, y luego hace backtest, optimiza y valida walk-forward la estrategia, todo offline.

uv sync --extra dev            # install
uv run orb-setup               # = python -m scripts.setup
uv run pytest -q               # = pytest -q
uv run python -m scripts.demo  # = python -m scripts.demo
uv run orb-dashboard           # = python -m dashboard.app
uv run python -m scripts.check_ibkr

orb-setup y orb-dashboard son los puntos de entrada de consola definidos en pyproject.toml; también están disponibles en tu PATH después de pip install -e ..

Panel de control (GUI)

Un panel web de solo lectura ofrece una vista clara de todo de un vistazo:

python -m dashboard.app       # (uv: uv run orb-dashboard)
# open http://127.0.0.1:8787

Muestra:

• Tarjetas de cuenta - entorno (insignia PAPER/LIVE), conexión IBKR, P&L diario, presupuesto de riesgo por operación, posiciones abiertas y estado del interruptor de apagado diario.

• Curva de capital - P&L acumulado de operaciones cerradas desde tu capital inicial.

• Señales en vivo - la lectura ORB actual por ventana de sesión (con un interruptor «Demo data» para que funcione sin IBKR).

• Rendimiento por ventana y por estrategia - tasa de aciertos, expectancia, factor de beneficio y P&L total, para que veas qué ventanas ORB y qué tipos de spread funcionan.

• Auto-trading (botón play) - un control de inicio/parada que ejecuta el bucle de entrada ORB automáticamente: en cada intervalo evalúa la ventana de sesión activa y, si una ruptura que cumple los requisitos pasa todas las compuertas de riesgo, coloca un spread dimensionado al riesgo (de papel o simulado) y lo registra. Las entradas usan el conjunto de parámetros que elijas (ranking del optimizador, historial de optimización o Use these for trading en los parámetros avanzados). Hasta que elijas uno, se aplican los valores por defecto de windows.json. Entra hasta 3 operaciones por ventana de sesión (máximo 9 al día entre Asia / Londres / Nueva York), respeta el límite por operación y el interruptor de apagado diario, y muestra un registro de actividad en vivo. Deshabilitado para cuentas LIVE como medida de seguridad: solo papel/simulado.

• Backtesting y simulación - elige un símbolo, ventana de sesión y retrospectiva, luego Run backtest para obtener datos históricos (historial IBKR en vivo, o datos demo sin conexión) y simular la estrategia de spreads ORB. Obtienes una curva de capital simulada, métricas completas (tasa de aciertos, expectancia, factor de beneficio, drawdown, Sharpe, Monte-Carlo) y cada operación simulada. Optimise hace una búsqueda por cuadrícula en el espacio de parámetros, clasifica los mejores conjuntos según la puntuación equilibrada y guarda el mejor.

• Optimizaciones realizadas - un historial de cada ejecución del optimizador con sus mejores parámetros y métricas, para que veas qué se ha probado y qué ha ganado.

• Posiciones abiertas - operaciones registradas más posiciones IBKR en vivo cuando hay conexión.

• Historial de operaciones - cada operación con la estrategia utilizada (p. ej. bull call debit, bull put credit), dirección, tamaño, pérdida máxima, estado y P&L realizado.

Se actualiza cada 8 segundos. El auto-trading (cuando lo inicias) coloca spreads de papel a través del proceso del panel; el resto de la ejecución permanece con el agente de ejecución. La vista se alimenta de data/trades.db; elimina ese archivo para restablecer un registro vacío.

Control remoto por Discord

El bot se ejecuta en este PC junto al panel y se comunica con http://127.0.0.1:8787. Los comandos de barra desde tu teléfono (o cualquier cliente de Discord) controlan el auto-trading en papel y transmiten eventos en vivo de vuelta.

1. Crea una aplicación en discord.com/developers/applications → Bot → copia el token en .env como DISCORD_BOT_TOKEN.

2. OAuth2 → URL Generator: scopes bot y applications.commands, permiso Send Messages. Abre la URL e invita al bot a un servidor que te pertenezca.

3. Discord User Settings → Advanced → Developer Mode. Haz clic derecho en tu avatar → Copy User ID → DISCORD_ALLOWED_USER_IDS. Haz clic derecho en el nombre del servidor → Copy Server ID → DISCORD_GUILD_ID (los comandos de barra aparecen de inmediato). Opcional: haz clic derecho en un canal → Copy Channel ID → DISCORD_LOG_CHANNEL_ID para publicaciones de ejecución / error / inicio / parada en vivo.

4. Mantén el panel en ejecución y, en una segunda terminal:

pip install -e ".[dev]"          # once, so discord.py is in .venv
python -m dashboard.app          # already running is fine; restart it once
python -m scripts.discord_bot    # or: orb-discord

Comandos: /help, /status, /signals, /preview, /positions, /trades, /auto start|stop|status, /optimise (clasifica, no aplica), /nightly (dry-run por defecto). /auto start se rechaza si ACCOUNT_MODE=LIVE. No existe ningún comando de Discord que coloque una orden IBKR real.

Verificación de la conexión IBKR

Con IB Gateway/TWS en ejecución e iniciada la sesión en la cuenta de papel:

python -m scripts.check_ibkr

Imprime el host/puerto/modo resueltos, se conecta y obtiene una cotización de ejemplo además del resumen de tu cuenta. Si falla, te dice exactamente qué comprobar. Guía completa en docs/IBKR_SETUP.md.

Datos históricos (backtests)

IBKR solo devuelve alrededor de un mes de barras de 5 minutos por solicitud. Para guardar en caché un año de historial de SPY localmente (usado por el backtest del panel / retrospectiva del optimizador 1 año):

python -m scripts.fetch_history --symbol SPY --days 365

Las barras se escriben en data/history/SPY_5mins.csv. Volver a ejecutar el comando reutiliza la caché cuando ya cubre la retrospectiva solicitada.

Ejecutar un servidor manualmente

Cada servidor habla MCP a través de stdio y normalmente lo lanza el cliente, pero puedes probar uno directamente con una prueba de humo:

python -m servers.market_data_mcp.server    # (uv: uv run python -m ...)

Los cuatro agentes (grupos de herramientas MCP)

El bucle de trading (cómo usa el cliente las herramientas)

1. market-data-mcp.get_session_orb -> dirección de ruptura + fuerza para la ventana activa.

2. market-data-mcp.classify_regime -> tendencia vs rango (elige spread débito vs crédito).

3. research-mcp.learn_from_history -> ¿tiene esta ventana/régimen expectancia positiva?

4. execution-mcp.preview_spread -> vertical de riesgo definido dimensionado al límite de riesgo.

5. execution-mcp.place_spread -> envía una orden combinada + bracket SL/TP (papel por defecto).

6. El resultado se registra mediante research-mcp.log_trade; optimiser-mcp refina los parámetros.

Operar en vivo (deliberadamente difícil)

El trading en vivo requiere ambas cosas:

• ACCOUNT_MODE=live, y

• LIVE_TRADING_CONFIRM=I_UNDERSTAND_THE_RISK

y apuntando IBKR_PORT a tu puerto TWS/Gateway en vivo. Si solo se establece una de ellas, el ejecutor se niega a operar. Empieza en papel durante semanas primero.

Docker

La pila Python (panel, bot de Discord, servidores MCP, configuraciones) es una sola imagen. IB Gateway sigue siendo un contenedor comunitario separado porque es una aplicación de escritorio Java.

copy .env.example .env            # then set IB_GATEWAY_USER / IB_GATEWAY_PASSWORD
docker compose up -d --build      # dashboard: http://127.0.0.1:8787

# Optional Discord bot (needs DISCORD_* in .env)
docker compose --profile discord up -d

Al hacer push a main también se publica la imagen en GitHub Container Registry:

docker pull ghcr.io/<owner>/options-orb-mcp:latest

Comandos puntuales en la imagen:

docker compose run --rm dashboard demo     # offline demo (no IBKR)
docker compose run --rm dashboard check    # IBKR connectivity

Los servidores MCP normalmente se ejecutan en el host (Cursor/Claude los lanzan a través de stdio). Están instalados en la imagen por si quieres ejecutarlos:

docker compose exec dashboard python -m servers.market_data_mcp.server

Otro PC (clonar esta máquina)

No copies .venv, .env ni .cursor/mcp.json: están vinculados a la ruta de Python y los secretos de este ordenador. Clona el repositorio y, en el PC nuevo:

git clone <your-repo-url> "Options Trading"
cd "Options Trading"
python -m venv .venv
.\.venv\Scripts\activate
pip install -e ".[dev]"
copy .env.example .env
# edit .env: IBKR_PORT=4002, ACCOUNT_MODE=paper
python -m scripts.setup
pytest -q

Luego, solo en ese PC:

1. Instala IB Gateway, inicia sesión en la misma cuenta de papel, habilita la API en el puerto 4002 (docs/IBKR_SETUP.md). La API es 127.0.0.1 — Gateway debe ejecutarse en esa máquina.

2. Opcional: copia data/history/SPY_5mins.csv desde este PC para omitir una descarga larga de historial. De lo contrario: python -m scripts.fetch_history --symbol SPY --days 365

3. No copies data/trades.db a menos que quieras el registro de este PC. Si el archivo no existe, es un registro de papel nuevo.

4. python -m dashboard.app → http://127.0.0.1:8787 y luego Start para el auto-trading.

5. Optimizador nocturno (23:30 GMT): python -m scripts.nightly_optimise --install-task

6. Reinicia Cursor para que los servidores MCP carguen .cursor/mcp.json.

Confírmalo con python -m scripts.check_ibkr. Después de un cambio de horario de verano de Windows, vuelve a ejecutar --install-task.

Estructura del repositorio

core/            shared library (config, models, db, pricing, risk, strategy, ibkr)
servers/         one MCP server per agent
dashboard/       read-only web GUI (Starlette API + single-page UI)
configs/         per-window ORB parameters
scripts/         setup / demo / check_ibkr / discord_bot / nightly_optimise
tests/           unit tests (pricing, ORB, risk, metrics)
data/            SQLite journal + backtest artifacts (gitignored)
docker/          container entrypoint
Dockerfile       Python stack image (dashboard, Discord, MCP servers)
docker-compose.yml  IB Gateway + dashboard (+ optional Discord)