Jupyter AI MCP for Codex

Reproducible project to run JupyterLab and expose its tools to Codex via MCP. Python dependencies are managed exclusively by uv.

Requirements

• uv

• Python 3.10 or higher (uv can install it)

• Codex Desktop, CLI, or extension for VS Code

• Docker Desktop, only if you choose to run in a container

Related MCP server: jupyter-interactive-mcp

Recommended execution in WSL2

A folder located at D:\Projetos\jupyter-ai-mcp-codex, for example, appears in WSL2 as /mnt/d/Projetos/jupyter-ai-mcp-codex.

After copying this project to the D: drive, open WSL2 and run:

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

The script uses exclusively paths relative to the project itself, runs uv sync --frozen from uv.lock, and creates a new local .venv. No path from OneDrive or the original user is embedded in the environment.

If uv is not yet installed in the WSL2 distribution, follow the official uv installation and then run the script again.

For better performance with many small files, the native WSL2 filesystem is usually faster than /mnt/d. Using D: remains valid and is suitable when the priority is keeping the files visible to Windows.

Local execution on Windows

In PowerShell, inside this folder:

.\scripts\start-local.ps1

The script runs uv sync --frozen and starts:

• JupyterLab: http://127.0.0.1:8888

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

Keep the terminal open. The JupyterLab URL with the access token will be displayed in the log.

Execution with Docker

.\scripts\start-docker.ps1

Or directly:

docker compose up --build

The ports are published only on the machine's loopback. Notebooks are persisted in notebooks/, inside the project folder itself.

To stop:

docker compose down

Connecting to Codex

This project includes .codex/config.toml with the server:

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

Open the copy located on the D: drive as a trusted project in Codex and restart Codex after starting JupyterLab. The configuration is local to the project; it does not change the global configuration in ~/.codex/config.toml.

If Codex is running on Windows and Jupyter on WSL2, first test http://127.0.0.1:3001/mcp. The WSL2 script makes MCP listen on 0.0.0.0 inside the distribution, and WSL2's localhost forwarding usually makes the port accessible from Windows. The provided configuration already uses that address. Do not publish port 3001 on the router or open a broad rule in Windows Firewall.

Verification

Check whether MCP is listening:

Test-NetConnection 127.0.0.1 -Port 3001

The expected result is TcpTestSucceeded : True. Then, in Codex, ask it to read or run notebooks/verificacao.ipynb using the Jupyter MCP tools.

In WSL2, the equivalent check is:

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

The MCP endpoint may respond that a valid MCP request is required; this still confirms that the HTTP server is reachable. The Jupyter logs should display MCP server started on port 3001.