Skip to main content
Glama

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: jupyter-interactive-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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Connects Codex to the FoggyKitchen MCP endpoint, enabling use of FoggyKitchen tools within Codex.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that gives any MCP-compatible LLM client full control over a live JupyterLab instance.
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables Claude Code to use remote MCP servers already authenticated in Codex by reusing Codex OAuth tokens and forwarding JSON-RPC messages without requiring a second OAuth flow.
      -