Jupyter AI MCP para Codex

Projeto reproduzivel para executar JupyterLab e expor suas ferramentas ao Codex por MCP. As dependencias Python sao gerenciadas exclusivamente pelo uv.

Requisitos

• uv

• Python 3.10 ou superior (o uv pode instala-lo)

• Codex Desktop, CLI ou extensao para VS Code

• Docker Desktop, apenas se voce escolher a execucao em container

Related MCP server: Claude Code Notebook MCP

Execucao no WSL2 recomendada

Uma pasta localizada em D:\Projetos\jupyter-ai-mcp-codex, por exemplo, aparece no WSL2 como /mnt/d/Projetos/jupyter-ai-mcp-codex.

Depois de copiar este projeto para a unidade D:, abra o WSL2 e execute:

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

O script usa exclusivamente caminhos relativos ao proprio projeto, executa uv sync --frozen a partir do uv.lock e cria um novo .venv local. Nenhum caminho do OneDrive ou do usuario original fica incorporado ao ambiente.

Se o uv ainda nao estiver instalado na distribuicao WSL2, siga a instalacao oficial do uv e depois execute o script novamente.

Para melhor desempenho com muitos arquivos pequenos, o filesystem nativo do WSL2 costuma ser mais rapido que /mnt/d. O uso em D: continua valido e e adequado quando a prioridade e manter os arquivos visiveis para o Windows.

Execucao local no Windows

No PowerShell, dentro desta pasta:

.\scripts\start-local.ps1

O script executa uv sync --frozen e inicia:

• JupyterLab: http://127.0.0.1:8888

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

Mantenha o terminal aberto. A URL do JupyterLab com o token de acesso sera exibida no log.

Execucao com Docker

.\scripts\start-docker.ps1

Ou diretamente:

docker compose up --build

As portas sao publicadas somente no loopback da maquina. Os notebooks ficam persistidos em notebooks/, dentro da propria pasta do projeto.

Para encerrar:

docker compose down

Conexao com o Codex

Este projeto inclui .codex/config.toml com o servidor:

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

Abra a copia localizada na unidade D: como projeto confiavel no Codex e reinicie o Codex depois de iniciar o JupyterLab. A configuracao e local ao projeto; ela nao altera a configuracao global em ~/.codex/config.toml.

Se o Codex estiver rodando no Windows e o Jupyter no WSL2, teste primeiro http://127.0.0.1:3001/mcp. O script WSL2 faz o MCP escutar em 0.0.0.0 dentro da distribuicao, e o encaminhamento de localhost do WSL2 normalmente torna a porta acessivel no Windows. A configuracao fornecida ja usa esse endereco. Nao publique a porta 3001 no roteador nem abra uma regra ampla no Firewall do Windows.

Verificacao

Confira se o MCP esta ouvindo:

Test-NetConnection 127.0.0.1 -Port 3001

O resultado esperado e TcpTestSucceeded : True. Depois, no Codex, solicite que ele leia ou execute notebooks/verificacao.ipynb usando as ferramentas do Jupyter MCP.

No WSL2, a verificacao equivalente e:

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

O endpoint MCP pode responder que uma requisicao MCP valida e necessaria; isso ainda confirma que o servidor HTTP esta acessivel. Os logs do Jupyter devem exibir MCP server started on port 3001.