mcp-ibkr

Eigener MCP-Server (Model Context Protocol) zur Verbindung von Claude Code mit Interactive Brokers (IBKR), beginnend im Nur-Lese-Modus auf einem Paper-Trading-Konto.

Projektstatus: 12 von 12 Phasen abgeschlossen. Siehe Abschnitt „Aktueller Stand".

1. Was ist dieses Projekt

Eine Brücke zwischen Claude Code und IBKR: Claude Code startet diesen Server, der Server stellt „Werkzeuge" (Funktionen mit Namen und Beschreibung) bereit, und Claude verwendet sie, wenn der Benutzer Informationen über das Konto, Positionen oder den Markt anfragt. Kein Werkzeug spricht direkt mit IBKR: Alle laufen über eine zentrale Integrationsschicht.

Related MCP server: IB Portfolio Tracker MCP Server

2. Architektur

Claude Code (cliente MCP)
      │  stdio / JSON-RPC
      v
Servidor MCP (src/server.py)
      │
      v
Tool Registry (src/tools/*)
      │
      v
Capa de integración IBKR (src/ibkr/*)
      │  ib_async → socket TCP
      v
IB Gateway (Paper Trading, puerto 4002)
      │
      v
Interactive Brokers

3. Ordnerstruktur

mcp-ibkr/
├── src/
│   ├── server.py          # Punto de entrada del servidor MCP
│   ├── ibkr/
│   │   └── connection.py     # UNICO lugar que habla con ib_async / IB Gateway
│   ├── tools/
│   │   ├── registry.py       # Registro central: conecta archivos de herramienta con el servidor
│   │   ├── account/            # Saldo, resumen de cuenta, verificar conexión
│   │   ├── market/              # Precio, cotización, históricos
│   │   ├── positions/            # Posiciones abiertas, P&L
│   │   └── orders/                # Consultar (activa) + crear/cancelar (ACTION, deshabilitadas)
│   ├── config/
│   │   └── settings.py       # Carga .env, rechaza arrancar en config insegura
│   └── utils/
│       └── risk.py            # RiskLevel: READ_ONLY / ACTION
├── tests/
├── .env.example
├── .gitignore
├── .mcp.json          # Registro del servidor para Claude Code (scope project)
├── pyproject.toml      # Configuracion de pytest
├── requirements.txt     # Dependencias exactas (pip freeze)
└── README.md

4. Voraussetzungen

• Python 3.11+ (getestet mit 3.14).

• Git.

• curl (zum Herunterladen von get-pip.py in Abschnitt 5 und des IB-Gateway-Installers in Abschnitt 6).

• IB Gateway installiert, mit gestarteter Paper-Trading-Sitzung (siehe Abschnitt 6).

5. Installation und Konfiguration

cd ~/mcp-ibkr

# Crear entorno virtual aislado para este proyecto
python3 -m venv --without-pip .venv

# Instalar pip dentro del venv (no viene incluido con --without-pip)
curl -sS https://bootstrap.pypa.io/get-pip.py -o /tmp/get-pip.py
.venv/bin/python3 /tmp/get-pip.py

# Instalar dependencias del proyecto
.venv/bin/python3 -m pip install -r requirements.txt

# Configuración local (nunca se sube a Git)
cp .env.example .env

Hinweis zu requirements.txt: Wir installieren nur 4 Pakete direkt (mcp, ib_async, python-dotenv, pytest), aber die Datei enthält viele weitere Zeilen, weil pip freeze auch die Abhängigkeiten dieser Pakete enthält (Abhängigkeiten ihrer Abhängigkeiten). Das ist normal – es bedeutet nicht, dass das Projekt all diese Bibliotheken direkt verwendet.

Hinweis: Auf Debian/Ubuntu-Systemen kann python3 -m venv allein fehlschlagen, wenn das Systempaket python3-venv fehlt (installierbar mit sudo apt install python3-venv). Wenn du keinen sudo-Zugriff hast, ergibt die Kombination --without-pip + manuelles Installieren von pip in der venv (die obigen Schritte) eine ebenso isolierte Umgebung ohne Administratorrechte.

6. Verbindung mit IBKR (Paper Trading)

1. Installiere IB Gateway (offizieller Download, stable-standalone):

   curl -o ibgateway-stable-standalone-linux-x64.sh \
     https://download.interactivebrokers.com/installers/ibgateway/stable-standalone/ibgateway-stable-standalone-linux-x64.sh
   chmod u+x ibgateway-stable-standalone-linux-x64.sh
   ./ibgateway-stable-standalone-linux-x64.sh

2. Öffne es und melde dich an, indem du explizit „Paper Trading" (nicht „Live Trading") auswählst, mit deinem Paper-Trading-Benutzernamen/-Passwort.

3. Überprüfe, dass der API-Port 4002 (Paper) ist. Du kannst das so bestätigen:

   ss -ltnp | grep 4002   # deberia aparecer un proceso "java" escuchando

4. Kopiere .env.example zu .env (falls noch nicht geschehen) und passe die Werte an, wenn deine Konfiguration abweicht.

Warum das sicher ist: src/config/settings.py verweigert den Start, wenn IBKR_PORT nicht exakt 4002 ist, und auch, wenn IBKR_PAPER_TRADING_CONFIRMED nicht true lautet. Außerdem wird die Verbindung (src/ibkr/connection.py) mit readonly=True geöffnet, wodurch IB Gateway jeden Versuch, Aufträge auf API-Ebene zu senden, ablehnt – sogar bevor es Auftragswerkzeuge gibt.

7. Konfiguration von Claude Code

Der Server ist in .mcp.json (Projektwurzel) mit Scope project registriert. Das bedeutet, dass die Datei in Git versioniert wird und jeder, der dieses Repo in Claude Code öffnet, den vorgeschlagenen Server sieht – aber er wird nicht automatisch ausgeführt: Claude Code markiert ihn als „Pending approval", bis du eine Sitzung in diesem Ordner öffnest und ihn genehmigst.

cd ~/mcp-ibkr
claude    # al iniciar, Claude Code te preguntará si confías en mcp-ibkr

Um den Serverstatus jederzeit zu überprüfen:

claude mcp list
claude mcp get mcp-ibkr

Falls du ihn jemals entfernen möchtest:

claude mcp remove mcp-ibkr -s project

8. Verfügbare Werkzeuge

9. So fügst du ein Werkzeug hinzu / änderst / löschst / deaktivierst es

Jedes Werkzeug ist eine Datei in src/tools/<kategorie>/ mit dieser Form (siehe src/tools/account/verificar_conexion_ibkr.py als reales Beispiel):

from mcp.types import ToolAnnotations
from src.utils.risk import RiskLevel

NAME = "mi_herramienta"
DESCRIPTION = "Que hace, cuando usarla, que devuelve, si modifica la cuenta."
ANNOTATIONS = ToolAnnotations(readOnlyHint=True, openWorldHint=True)
ENABLED = True
RISK_LEVEL = RiskLevel.READ_ONLY  # o RiskLevel.ACTION si modifica algo

def mi_herramienta(parametro: str) -> str:
    return "resultado"

Die Funktion muss genau wie NAME heißen – so findet sie die zentrale Registrierung (src/tools/registry.py) automatisch. Wenn RISK_LEVEL gleich ACTION ist, braucht es zusätzlich zu ENABLED = True auch IBKR_ENABLE_ACTION_TOOLS=true in .env (siehe Abschnitt 11) – zwei unabhängige Schlüssel, bewusst so.

Zu ANNOTATIONS: destructiveHint und idempotentHint sind nur bedeutsam, wenn readOnlyHint=False ist (so dokumentiert es die MCP-Spezifikation) – deshalb reicht bei einem Nur-Lese-Werkzeug readOnlyHint und openWorldHint. Füge sie nur hinzu, wenn RISK_LEVEL gleich ACTION ist, wie in src/tools/orders/crear_orden.py.

Ein Werkzeug hinzufügen

1. Erstelle die Datei in der entsprechenden Kategorie (oder erstelle eine neue Kategorie, siehe unten).

2. Füge den Dateinamen (ohne .py) zur Liste TOOLS im __init__.py dieser Kategorie hinzu.

3. Starte die Claude-Code-Sitzung neu, damit es erkannt wird (Claude Code liest die Werkzeuge nur einmal, beim Start des Servers; claude mcp list fragt nur den Verbindungsstatus ab, lädt nichts neu).

Ein Werkzeug ändern

Bearbeite direkt seine Datei – DESCRIPTION, Funktionsparameter, interne Logik usw. registry.py muss nicht angefasst werden.

Ein Werkzeug löschen

Lösche die Datei und entferne ihren Namen aus TOOLS im __init__.py ihrer Kategorie.

Ein Werkzeug deaktivieren (ohne es zu löschen)

Setze ENABLED = False in seiner Datei. registry.py überspringt es automatisch.

Eine neue Kategorie erstellen

Erstelle den Ordner src/tools/<kategorie>/ mit einem __init__.py, das TOOLS: list[str] = [...] definiert, und füge den Kategorienamen zu CATEGORIES in src/tools/registry.py hinzu.

10. Testing

cd ~/mcp-ibkr
.venv/bin/python3 -m pytest tests/ -v

• tests/test_server.py – der Server startet und stellt die erwarteten Werkzeuge bereit (dasselbe, was Claude Code beim Verbinden sehen würde); die Nur-Lese-Werkzeuge setzen keine Anmerkungen, die nicht zutreffen; und jedes Werkzeug antwortet mit einer freundlichen Meldung, wenn IBKR nicht verfügbar ist, statt eine Ausnahme durchsickern zu lassen.

• tests/test_settings.py – die Konfiguration weist einen anderen Port als 4002 und das Fehlen von IBKR_PAPER_TRADING_CONFIRMED zurück.

• tests/test_connection.py – die Verbindungsschicht serialisiert die Verbindungsversuche (mit simuliertem IBKR, kein echtes Gateway erforderlich): Wenn zwei Werkzeuge fast gleichzeitig aufgerufen werden, laufen nie zwei Verbindungsversuche parallel.

• tests/test_risk_system.py – die ACTION-Werkzeuge (crear_orden, cancelar_orden) werden standardmäßig nicht registriert, und die Validierungen eines Auftrags (Menge, Typ, Preis) lehnen ungültige Parameter ab.

• tests/test_ibkr_integration.py – echte Verbindung gegen IB Gateway. Wenn Gateway nicht läuft, wird dieser Test übersprungen (schlägt nicht fehl) – das ist erwartet, kein Fehler des Projekts.

Alle auftragsbezogenen Tests verwenden validar_parametros_orden isoliert (ohne IBKR zu berühren) oder hängen davon ab, dass crear_orden standardmäßig deaktiviert ist: Kein Test dieses Projekts sendet einen echten Auftrag, nicht einmal im Paper Trading.

11. Von Paper Trading zu Live Trading

⚠️ Live Trading wird von diesem Projekt noch nicht unterstützt, und crear_orden/cancelar_orden sind standardmäßig deaktiviert. Das Folgende ist die Erklärung der Sicherheitsebenen, keine Einladung, sie unüberlegt zu aktivieren.

Es gibt drei unabhängige Ebenen, die verhindern, dass versehentlich ein echter Auftrag gesendet wird:

1. Pflichtport 4002 – src/config/settings.py verweigert den Start, wenn IBKR_PORT nicht exakt der Paper-Trading-Port ist. Diese Version des Projekts hat keinen Codepfad zur Verwendung von Port 4001 (Live).

2. Doppelschlüssel für ACTION-Werkzeuge – crear_orden und cancelar_orden benötigen ENABLED = True in ihrer eigenen Datei und IBKR_ENABLE_ACTION_TOOLS=true in .env. Keine der beiden ist standardmäßig aktiviert. Beide werden nur beim Start des Servers gelesen: Wenn du sie bei laufendem Server änderst, musst du die Claude-Code-Sitzung neu starten, damit die Änderung wirksam wird.

3. Nur-Lese-Verbindung auf API-Ebene – solange IBKR_ENABLE_ACTION_TOOLS gleich false ist, verbindet sich src/ibkr/connection.py mit readonly=True: IB Gateway lehnt jeden Auftrag ab, selbst wenn es jemandem gelänge, die beiden vorherigen Ebenen zu umgehen.

Wenn du in Zukunft entscheidest, das Senden von Aufträgen im Paper Trading zu aktivieren, wäre der Weg: die Validierungen von src/tools/orders/crear_orden.py überprüfen und verstärken, IBKR_ENABLE_ACTION_TOOLS=true in .env setzen und ENABLED = True in den Auftragsdateien. Unterstützung für echtes Live Trading ist in diesem Projekt weder implementiert noch geplant – es wäre eine vollständig separate Sicherheitsüberprüfung erforderlich, bevor man es in Betracht zieht.

12. Aktueller Stand

• Phase 1 – Architektur und Konzepte

• Phase 2 – Minimale Projektstruktur

• Phase 3 – Entwicklungsumgebung

• Phase 4 – Minimaler MCP-Server

• Phase 5 – Claude Code mit dem MCP verbinden

• Phase 6 – Erstes Testwerkzeug

• Phase 7 – Verbindung mit IB Gateway (Paper Trading)

• Phase 8 – Abfragewerkzeuge

• Phase 9 – Validierungs- und Risikosystem

• Phase 10 – Auftragswerkzeuge (gesperrt)

• Phase 11 – Vollständiges Testing

• Phase 12 – Abschließende Dokumentation