Options ORB MCP System

Ein demo-first-System von MCP-Servern, die Marktanalyse-, Research-, Optimierungs- und Ausführungswerkzeuge für einen LLM-Client (Cursor / Claude Desktop) bereitstellen. Es handelt mit Options-Vertikal-Spreads mit definiertem Risiko, gesteuert durch ein Opening-Range-Breakout (ORB)-Signal, optimiert pro Sitzungsfenster (Asien / London / New York), mit strengen Risikokontrollen, ausgelegt für ~£1000 Kapital.

Risikohinweis. Dies ist Bildungssoftware, keine Finanzberatung. Der Handel mit Optionen birgt das Risiko von Kapitalverlusten. Das System verwendet standardmäßig ein Paper-Konto und lehnt die Platzierung echter Aufträge ab, es sei denn, Sie betätigen bewusst zwei unabhängige Sicherheitsschalter. „Stetige Renditen" sind ein Design-Ziel, niemals eine Garantie.

Warum das Design so aussieht

• Ihre Aufgabenbeschreibung nannte ORB, Sitzungsfenster, SL/TP und MetaTrader. Echte Optionen (Strikes/Verfallsdaten/Griechen) leben nicht auf MT5, daher verwendet dieses System Interactive Brokers (Paper-API + UK-Zugang + US-Optionen).

• £1000 bedeutet nur Spreads mit definiertem Risiko (vertikale). Das ORB-Breakout auf dem Basiswert ist das Richtungssignal; der Ausführungs-Agent platziert den Spread.

• Die Sitzungsfenster werden für US-Optionen neu gefasst: Asien = nächtlicher Globex-Bereich, London = EU/vorbörslich, New York = das klassische ORB bei der US-Eröffnung.

Related MCP server: IBKR TWS MCP Server

Architektur

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)

Voraussetzungen

1. Python 3.11+ (3.13 getestet).

2. Eine virtuelle Umgebung mit pip (Schritte unten). uv wird als optionale Alternative unterstützt, falls Sie es haben.

3. Interactive Brokers-Konto mit aktiviertem Paper-Trading sowie TWS oder IB Gateway, das mit aktivierter API läuft (Configure -> API -> Settings -> „Enable ActiveX and Socket Clients").

   • Paper-Standardwerte: TWS 7497, IB Gateway 4002.

   • Neu hier? Folgen Sie der Schritt-für-Schritt-IBKR-Einrichtungsanleitung (Gateway installieren, bei Paper anmelden, API aktivieren, kostenlose verzögerte Daten).

Paper-Trading verwendet standardmäßig Live-IBKR-Daten; synthetische/„Demo-Daten" sind nur ein expliziter Offline-Umschalter. Backtester und Preistools funktionieren ohne IBKR – nur für Live-Marktdaten und Orderplatzierung muss Gateway/TWS laufen. Paper-Konten erhalten kostenlose, um 15 Minuten verzögerte Daten, und das System greift automatisch darauf zurück, wenn Sie kein Echtzeit-Abonnement haben.

Einrichtung

Führen Sie diese Befehle vom Stammverzeichnis des Repositorys aus. Die Befehle setzen voraus, dass Ihre virtuelle Umgebung aktiviert ist (sodass python/pytest auf .venv zeigen).

# 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

Die Demo testet jeden Agenten Ende-zu-Ende: Sie findet ein ORB-Breakout, dimensioniert einen Spread mit definiertem Risiko, simuliert eine Paper-Ausführung, protokolliert sie und backtestet, optimiert und walk-forward-validiert anschließend die Strategie – alles 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 und orb-dashboard sind die in pyproject.toml definierten Console-Script-Einstiegspunkte; sie sind nach pip install -e . auch in Ihrem PATH verfügbar.

Dashboard (GUI)

Ein schreibgeschütztes Web-Dashboard bietet einen klaren Überblick über alles auf einen Blick:

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

Es zeigt:

• Kontokarten – Umgebung (PAPER/LIVE-Abzeichen), IBKR-Verbindung, täglicher P&L, Risikobudget pro Trade, offene Positionen und Status des täglichen Kill-Switches.

• Eigenkapitalkurve – kumulativer P&L der geschlossenen Trades ab Ihrem Startkapital.

• Live-Signale – die aktuelle ORB-Ablesung pro Sitzungsfenster (mit einem „Demo data"-Umschalter, sodass es ohne IBKR funktioniert).

• Performance nach Fenster und Strategie – Gewinnquote, Erwartungswert, Profitfaktor und gesamter P&L, sodass Sie sehen, welche ORB-Fenster und welche Spread-Typen funktionieren.

• Auto-Trading (Play-Button) – eine Start/Stopp-Steuerung, die die ORB-Einstiegsschleife automatisch ausführt: In jedem Intervall wertet sie das aktive Sitzungsfenster aus und platziert, wenn ein qualifizierendes Breakout jedes Risiko-Gate passiert, einen risikodimensionierten Spread (Paper oder simuliert) und protokolliert ihn. Einstiege verwenden den Parametersatz, den Sie wählen (Optimierer-Ranking, Optimierungsverlauf oder Use these for trading bei den erweiterten Parametern). Bis Sie einen wählen, gelten die windows.json-Standardwerte. Es tätigt bis zu 3 Trades pro Sitzungsfenster (max. 9 pro Tag über Asien / London / New York), respektiert die Obergrenze pro Trade und den täglichen Kill-Switch und zeigt ein Live-Aktivitätsprotokoll. Für LIVE-Konten deaktiviert als Sicherheitsmaßnahme – nur Paper/simuliert.

• Backtesting & Simulation – Symbol, Sitzungsfenster und Lookback wählen, dann Run backtest ausführen, um historische Daten abzurufen (Live-IBKR-Verlauf oder Offline-Demodaten) und die ORB-Spread-Strategie zu simulieren. Sie erhalten eine simulierte Eigenkapitalkurve, vollständige Kennzahlen (Gewinnquote, Erwartungswert, Profitfaktor, Drawdown, Sharpe, Monte-Carlo) und jeden simulierten Trade. Optimise durchsucht den Parameterraum per Grid-Search, ordnet die besten Sätze nach dem ausgewogenen Score und speichert den besten.

• Durchgeführte Optimierungen – ein Verlauf jedes Optimierungslaufs mit seinen besten Parametern und Kennzahlen, sodass Sie sehen, was versucht wurde und was gewonnen hat.

• Offene Positionen – Journal-Trades plus Live-IBKR-Positionen, wenn verbunden.

• Trade-Verlauf – jeder Trade mit der verwendeten Strategie (z. B. bull call debit, bull put credit), Richtung, Größe, maximalem Verlust, Status und realisiertem P&L.

Das Dashboard aktualisiert sich alle 8 Sekunden. Auto-Trade (wenn Sie ihn starten) platziert Paper-Spreads über den Dashboard-Prozess; die übrige Ausführung bleibt beim Ausführungs-Agenten. Die Ansicht wird aus data/trades.db befüllt; löschen Sie diese Datei, um auf ein leeres Journal zurückzusetzen.

Discord-Fernsteuerung

Der Bot läuft auf diesem PC neben dem Dashboard und spricht mit http://127.0.0.1:8787. Slash-Befehle von Ihrem Telefon (oder einem beliebigen Discord-Client) steuern dann das Paper-Auto-Trading und streamen Live-Ereignisse zurück.

1. Erstellen Sie eine Anwendung unter discord.com/developers/applications → Bot → kopieren Sie das Token in .env als DISCORD_BOT_TOKEN.

2. OAuth2 → URL Generator: Scopes bot und applications.commands, Berechtigung Send Messages. Öffnen Sie die URL und laden Sie den Bot auf einen Server ein, den Sie besitzen.

3. Discord User Settings → Advanced → Developer Mode. Klicken Sie mit der rechten Maustaste auf Ihren Avatar → Copy User ID → DISCORD_ALLOWED_USER_IDS. Klicken Sie mit der rechten Maustaste auf den Servernamen → Copy Server ID → DISCORD_GUILD_ID (Slash-Befehle erscheinen sofort). Optional: Klicken Sie mit der rechten Maustaste auf einen Kanal → Copy Channel ID → DISCORD_LOG_CHANNEL_ID für Live-Fill-/Fehler-/Start-/Stopp-Beiträge.

4. Lassen Sie das Dashboard laufen und öffnen Sie dann ein zweites 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

Befehle: /help, /status, /signals, /preview, /positions, /trades, /auto start|stop|status, /optimise (ordnet, wendet nicht an), /nightly (Standard: Dry-Run). /auto start wird verweigert, wenn ACCOUNT_MODE=LIVE ist. Es gibt keinen Discord-Befehl, der eine Live-IBKR-Order platziert.

Überprüfen der IBKR-Verbindung

Wenn IB Gateway/TWS läuft und Sie beim Paper-Konto angemeldet sind:

python -m scripts.check_ibkr

Es gibt den aufgelösten Host/Port/Modus aus, verbindet sich und ruft ein Beispiel-Quote sowie Ihre Kontozusammenfassung ab. Wenn es fehlschlägt, sagt es Ihnen genau, was Sie prüfen sollen. Die vollständige Anleitung finden Sie in docs/IBKR_SETUP.md.

Historische Daten (Backtests)

IBKR liefert pro Anfrage nur etwa einen Monat an 5-Minuten-Balken. Um ein Jahr SPY-Verlauf lokal zwischenzuspeichern (verwendet vom Dashboard-Backtest / Optimierer-Lookback 1 Jahr):

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

Die Balken werden nach data/history/SPY_5mins.csv geschrieben. Bei erneuter Ausführung des Befehls wird der Cache wiederverwendet, wenn er den angeforderten Lookback bereits abdeckt.

Manuelles Ausführen eines Servers

Jeder Server spricht MCP über stdio und wird normalerweise vom Client gestartet, aber Sie können einen direkt einem Smoke-Test unterziehen:

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

Die vier Agenten (MCP-Werkzeuggruppen)

Die Handelsschleife (wie der Client die Werkzeuge nutzt)

1. market-data-mcp.get_session_orb -> Breakout-Richtung + Stärke für das aktive Fenster.

2. market-data-mcp.classify_regime -> Trend vs. Range (wählt Debit- oder Credit-Spread).

3. research-mcp.learn_from_history -> Hat dieses Fenster/dieses Regime eine positive Erwartung?

4. execution-mcp.preview_spread -> Vertikaler Spread mit definiertem Risiko, dimensioniert auf die Risikoobergrenze.

5. execution-mcp.place_spread -> übermittelt Combo-Order + SL/TP-Bracket (standardmäßig Paper).

6. Das Ergebnis wird über research-mcp.log_trade protokolliert; optimiser-mcp verfeinert die Parameter.

Live gehen (bewusst schwer)

Live-Handel erfordert beides:

• ACCOUNT_MODE=live und

• LIVE_TRADING_CONFIRM=I_UNDERSTAND_THE_RISK

sowie das Setzen von IBKR_PORT auf Ihren Live-TWS/Gateway-Port. Wenn nur eines gesetzt ist, weigert sich der Ausführungs-Agent zu handeln. Starten Sie zuerst wochenlang auf Paper.

Docker

Der Python-Stack (Dashboard, Discord-Bot, MCP-Server, Konfigurationen) ist ein Image. IB Gateway bleibt ein separater Community-Container, da es eine Java-Desktop-Anwendung ist.

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

Wenn Sie main pushen, wird das Image auch in der GitHub Container Registry veröffentlicht:

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

Einmalbefehle im Image:

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

MCP-Server laufen typischerweise weiterhin auf dem Host (Cursor/Claude starten sie über stdio). Sie sind im Image installiert, wenn Sie sie per exec ausführen möchten:

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

Ein anderer PC (diese Maschine klonen)

Kopieren Sie nicht .venv, .env oder .cursor/mcp.json – diese sind an den Python-Pfad und die Geheimnisse dieses Computers gebunden. Klonen Sie das Repository und führen Sie dann auf dem neuen PC aus:

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

Dann nur auf diesem PC:

1. Installieren Sie IB Gateway, melden Sie sich beim selben Paper-Konto an, aktivieren Sie die API auf Port 4002 (docs/IBKR_SETUP.md). Die API ist 127.0.0.1 – Gateway muss auf dieser Maschine laufen.

2. Optional: Kopieren Sie data/history/SPY_5mins.csv von diesem PC, um einen langen Verlaufsdownload zu überspringen. Andernfalls: python -m scripts.fetch_history --symbol SPY --days 365

3. Lassen Sie data/trades.db zurück, es sei denn, Sie möchten das Journal dieses PCs. Eine fehlende Datei ist ein frisches Paper-Journal.

4. python -m dashboard.app → http://127.0.0.1:8787 und klicken Sie dann auf Start für Auto-Trading.

5. Nächtlicher Optimierer (23:30 GMT): python -m scripts.nightly_optimise --install-task

6. Starten Sie Cursor neu, damit die MCP-Server .cursor/mcp.json übernehmen.

Bestätigen Sie mit python -m scripts.check_ibkr. Nach einer Windows-Umstellung auf Sommer-/Winterzeit führen Sie --install-task erneut aus.

Repository-Struktur

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)