Jupyter AI MCP für Codex

Reproduzierbares Projekt zum Ausführen von JupyterLab und zum Bereitstellen seiner Werkzeuge für Codex über MCP. Die Python-Abhängigkeiten werden ausschließlich von uv verwaltet.

Anforderungen

• uv

• Python 3.10 oder höher (uv kann es installieren)

• Codex Desktop, CLI oder Erweiterung für VS Code

• Docker Desktop, nur wenn Sie die Ausführung im Container wählen

Related MCP server: Claude Code Notebook MCP

Empfohlene Ausführung unter WSL2

Ein Ordner, der sich beispielsweise unter D:\Projetos\jupyter-ai-mcp-codex befindet, erscheint in WSL2 als /mnt/d/Projetos/jupyter-ai-mcp-codex.

Nachdem Sie dieses Projekt auf das Laufwerk D: kopiert haben, öffnen Sie WSL2 und führen Sie Folgendes aus:

cd /mnt/d/Projetos/jupyter-ai-mcp-codex
bash scripts/start-local.sh

Das Skript verwendet ausschließlich relative Pfade zum Projekt selbst, führt uv sync --frozen auf Grundlage der uv.lock aus und erstellt ein neues lokales .venv. Kein Pfad von OneDrive oder vom ursprünglichen Benutzer wird in die Umgebung eingebettet.

Falls uv in der WSL2-Distribution noch nicht installiert ist, folgen Sie der offiziellen Installation von uv und führen Sie das Skript anschließend erneut aus.

Für eine bessere Leistung bei vielen kleinen Dateien ist das native Dateisystem von WSL2 in der Regel schneller als /mnt/d. Die Nutzung auf D: bleibt gültig und ist geeignet, wenn die Priorität darin besteht, die Dateien für Windows sichtbar zu halten.

Lokale Ausführung unter Windows

Führen Sie in PowerShell innerhalb dieses Ordners Folgendes aus:

.\scripts\start-local.ps1

Das Skript führt uv sync --frozen aus und startet:

• JupyterLab: http://127.0.0.1:8888

• MCP: http://127.0.0.1:3001/mcp

Lassen Sie das Terminal geöffnet. Die URL von JupyterLab mit dem Zugriffstoken wird im Log angezeigt.

Ausführung mit Docker

.\scripts\start-docker.ps1

Oder direkt:

docker compose up --build

Die Ports werden nur im Loopback der Maschine veröffentlicht. Die Notebooks werden persistent in notebooks/ innerhalb des Projektordners selbst gespeichert.

Zum Beenden:

docker compose down

Verbindung mit Codex

Dieses Projekt enthält .codex/config.toml mit dem Server:

[mcp_servers.jupyter-mcp]
url = "http://127.0.0.1:3001/mcp"

Öffnen Sie die auf dem Laufwerk D: befindliche Kopie als vertrauenswürdiges Projekt in Codex und starten Sie Codex neu, nachdem Sie JupyterLab gestartet haben. Die Konfiguration gilt nur für das Projekt; sie ändert nicht die globale Konfiguration unter ~/.codex/config.toml.

Wenn Codex unter Windows und Jupyter unter WSL2 läuft, testen Sie zuerst http://127.0.0.1:3001/mcp. Das WSL2-Skript lässt den MCP-Server innerhalb der Distribution auf 0.0.0.0 lauschen, und die localhost-Weiterleitung von WSL2 macht den Port normalerweise unter Windows erreichbar. Die mitgelieferte Konfiguration verwendet diese Adresse bereits. Veröffentlichen Sie Port 3001 nicht im Router und öffnen Sie keine weitgefasste Regel in der Windows-Firewall.

Überprüfung

Prüfen Sie, ob der MCP-Server lauscht:

Test-NetConnection 127.0.0.1 -Port 3001

Das erwartete Ergebnis ist TcpTestSucceeded : True. Bitten Sie dann in Codex darum, notebooks/verificacao.ipynb mithilfe der Werkzeuge des Jupyter MCP zu lesen oder auszuführen.

Unter WSL2 lautet die entsprechende Überprüfung:

curl --silent --output /dev/null --write-out '%{http_code}\n' \
  http://127.0.0.1:3001/mcp

Der MCP-Endpunkt kann antworten, dass eine gültige MCP-Anfrage erforderlich ist; das bestätigt dennoch, dass der HTTP-Server erreichbar ist. Die Jupyter-Logs sollten MCP server started on port 3001 anzeigen.