IBKR MCP-Server

Ein Model Context Protocol (MCP)-Server, der KI-Modellen über die TWS-API sicheren Zugriff auf Handelsdaten und Funktionen von Interactive Brokers (IBKR) bietet.

⚠️⚠️⚠️ Haftungsausschluss ⚠️⚠️⚠️

Diese Software dient zu Bildungs- und Entwicklungszwecken. Die Nutzung erfolgt auf eigenes Risiko. Die Autoren sind nicht für finanzielle Verluste verantwortlich, die durch die Nutzung dieser Software entstehen. Testen Sie immer mit einem Paper-Trading-Konto, bevor Sie echtes Geld verwenden.

Related MCP server: IBKR TWS MCP Server

🚀 Funktionen

• Kontoverwaltung: Abrufen von Positionen, Portfoliodetails und Kontozusammenfassungen

• Marktdaten: Abrufen historischer Preisdaten und Echtzeit-Marktinformationen

• Handelsoperationen: Platzieren von Aufträgen, Verwalten von Positionen und Nachverfolgen von Ausführungen

• MCP-Integration: Nahtlose Integration mit KI-Modellen, die das MCP-Protokoll unterstützen

• One-Shot-CLI: Verbinden-Ausführen-Trennen pro Befehl für schnelles Scripting

• Automatisierter TWS-Start (macOS): Ein Befehl zum Starten von TWS und automatischen Ausfüllen der TOTP-2FA

• Claude Code Skill: Handel per natürlicher Sprache über das mitgelieferte skills/ibkr-trading

• Sicherheitsfunktionen: Schreibgeschützter Modus, konfigurierbare Handelsbeschränkungen und umfassende Validierung

• Hohe Verfügbarkeit: Automatische Wiederverbindung, Heartbeat-Überwachung und saubere Fehlerbehandlung

📋 Voraussetzungen

• Python 3.10+

• Interactive Brokers TWS oder IB Gateway

• Aktives IBKR-Konto (Paper-Trading für Tests empfohlen)

🛠️ Installation

1. Repository klonen:

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

2. Abhängigkeiten installieren:

   pip install -r requirements.txt

3. TWS/IB Gateway konfigurieren:

   • API-Verbindungen in den TWS/Gateway-Einstellungen aktivieren

   • Socket-Port festlegen (Standard: 7497 für Paper-Trading, 7496 für Live)

   • Vertrauenswürdige IP-Adressen bei Bedarf konfigurieren

4. Server konfigurieren:

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

🚀 Verwendung

Option A: MCP-Server

python run.py

Der Server wird:

1. Eine Verbindung zu TWS/IB Gateway herstellen

2. Den MCP-Server auf dem konfigurierten Port starten

3. Die Heartbeat-Überwachung beginnen

4. Alle Aktivitäten protokollieren

Option B: One-Shot-CLI

Leichtgewichtige CLI, die pro Befehl eine Verbindung herstellt und sich wieder beendet – gut geeignet für Shell-Skripte oder Ad-hoc-Abfragen.

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

Führen Sie python cli.py --help für die vollständige Befehlsliste aus.

Hinweis zu Kursdaten: Wenn Sie kein Live-Marktdaten-Abonnement haben, greift quote auf den aktuellsten Tagesbalken über historische Daten zurück (keine Echtzeit-Felder).

Option C: Automatisierter TWS-Start (nur macOS)

start_tws.py startet TWS über IBC, erkennt den Dialog für die Zwei-Faktor-Authentifizierung, generiert einen TOTP-Code mit pyotp und gibt ihn per AppleScript (osascript) ein – vollautomatischer Login, ohne die Tastatur zu berühren.

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

Anforderungen (macOS):

Einrichtung:

1. Installieren Sie IBC gemäß den macOS-Anweisungen (normalerweise unter ~/ibc/).

2. Setzen Sie in ~/ibc/config.ini:

   • TradingMode=live (oder paper)

   • SecondFactorDevice=Mobile Authenticator

   • Ihre IBKR-Zugangsdaten

3. Speichern Sie Ihr IBKR-TOTP-Geheimnis (die Base32-Zeichenfolge aus dem QR-Code des Authenticators) in ~/.ibkr-totp-secret oder exportieren Sie es als TOTP_SECRET.

4. Erteilen Sie dem Terminal (oder Ihrem Python-Launcher) die Berechtigung für Bedienungshilfen unter Systemeinstellungen → Datenschutz & Sicherheit → Bedienungshilfen – erforderlich, damit AppleScript mit dem TWS-Fenster interagieren kann.

Plattform-Hinweis: start_tws.py basiert auf AppleScript/osascript und ist nur für macOS. Linux/Windows-Benutzer sollten entweder direkt IBC verwenden oder die GUI-Automatisierungsschicht anpassen (z. B. xdotool unter Linux, pywinauto unter Windows).

Verfügbare MCP-Tools

Kontowerkzeuge

• get_positions() - Aktuelle Kontopositionen abrufen

• get_account_summary() - Kontostand und Kennzahlen abrufen

• get_portfolio() - Detaillierte Portfolioinformationen abrufen

Marktdatenwerkzeuge

• get_historical_data(symbol, duration, bar_size) - Historische Preisdaten abrufen

• get_market_data(symbol) - Echtzeit-Marktdaten abrufen

• get_quote_from_history(symbol) - Letzter Tagesbalken als Kurs (kein Abonnement erforderlich)

• get_contract_details(symbol) - Vertragsspezifikationen abrufen

• get_option_chain - Optionsdaten abrufen

Handelswerkzeuge

• place_order(symbol, action, quantity, order_type, ...) - Kauf-/Verkaufsaufträge platzieren

• get_orders(status) - Auftragshistorie und Status abrufen

• cancel_order(order_id) - Ausstehende Aufträge stornieren

• get_trades() - Ausführungshistorie abrufen

Beispiel-KI-Interaktionen

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")

🤖 Claude Code Skill

Ein begleitender Skill befindet sich unter skills/ibkr-trading/SKILL.md. Er ermöglicht es Claude Code, die oben genannten CLI-Befehle über Prompts in natürlicher Sprache auszuführen (z. B. "zeige meine Positionen", "kurs von AAPL").

Zur Installation verknüpfen Sie ihn symbolisch mit Ihrem Claude Code Skills-Verzeichnis:

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

🔗 Verwandte Links & Credits

• Interactive Brokers TWS API — offizielle Python-API (ibapi)

• IBC — Interactive Brokers Controller — TWS-Autostarter (verwendet von start_tws.py)

• pyotp — TOTP/HOTP-Bibliothek (verwendet von start_tws.py)

• Model Context Protocol Specification

• FastMCP Framework

• Claude Code — KI-Pair-Programming-CLI, die den gebündelten Skill nutzt