Jupyter AI MCP para Codex

Proyecto reproducible para ejecutar JupyterLab y exponer sus herramientas a Codex mediante MCP. Las dependencias de Python se gestionan exclusivamente con uv.

Requisitos

• uv

• Python 3.10 o superior (uv puede instalarlo)

• Codex Desktop, CLI o extensión para VS Code

• Docker Desktop, solo si eliges la ejecución en contenedor

Related MCP server: jupyter-interactive-mcp

Ejecución en WSL2 recomendada

Una carpeta ubicada en D:\Projetos\jupyter-ai-mcp-codex, por ejemplo, aparece en WSL2 como /mnt/d/Projetos/jupyter-ai-mcp-codex.

Después de copiar este proyecto a la unidad D:, abre WSL2 y ejecuta:

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

El script usa exclusivamente rutas relativas al propio proyecto, ejecuta uv sync --frozen a partir de uv.lock y crea un nuevo .venv local. Ninguna ruta de OneDrive ni del usuario original queda incorporada al entorno.

Si uv aún no está instalado en la distribución WSL2, sigue la instalación oficial de uv y luego ejecuta el script de nuevo.

Para mejor rendimiento con muchos archivos pequeños, el sistema de archivos nativo de WSL2 suele ser más rápido que /mnt/d. El uso en D: sigue siendo válido y es adecuado cuando la prioridad es mantener los archivos visibles para Windows.

Ejecución local en Windows

En PowerShell, dentro de esta carpeta:

.\scripts\start-local.ps1

El script ejecuta uv sync --frozen e inicia:

• JupyterLab: http://127.0.0.1:8888

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

Mantén la terminal abierta. La URL de JupyterLab con el token de acceso se mostrará en el registro.

Ejecución con Docker

.\scripts\start-docker.ps1

O directamente:

docker compose up --build

Los puertos se publican solo en el loopback de la máquina. Los notebooks se conservan en notebooks/, dentro de la propia carpeta del proyecto.

Para finalizar:

docker compose down

Conexión con Codex

Este proyecto incluye .codex/config.toml con el servidor:

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

Abre la copia ubicada en la unidad D: como proyecto de confianza en Codex y reinicia Codex después de iniciar JupyterLab. La configuración es local al proyecto; no altera la configuración global en ~/.codex/config.toml.

Si Codex se está ejecutando en Windows y Jupyter en WSL2, prueba primero http://127.0.0.1:3001/mcp. El script de WSL2 hace que MCP escuche en 0.0.0.0 dentro de la distribución, y el reenvío de localhost de WSL2 normalmente hace que el puerto sea accesible desde Windows. La configuración proporcionada ya usa esa dirección. No publiques el puerto 3001 en el router ni abras una regla amplia en el Firewall de Windows.

Verificación

Comprueba si MCP está escuchando:

Test-NetConnection 127.0.0.1 -Port 3001

El resultado esperado es TcpTestSucceeded : True. Después, en Codex, pídele que lea o ejecute notebooks/verificacao.ipynb usando las herramientas del Jupyter MCP.

En WSL2, la verificación equivalente es:

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

El endpoint MCP puede responder que se necesita una solicitud MCP válida; eso todavía confirma que el servidor HTTP es accesible. Los registros de Jupyter deben mostrar MCP server started on port 3001.