用于 Codex 的 Jupyter AI MCP

可复现项目，用于运行 JupyterLab 并通过 MCP 将其工具暴露给 Codex。 Python 依赖完全由 uv 管理。

要求

• uv

• Python 3.10 或更高版本（uv 可以安装它）

• Codex Desktop、CLI 或 VS Code 扩展

• Docker Desktop，仅当你选择容器运行时需要

Related MCP server: Claude Code Notebook MCP

推荐在 WSL2 中运行

例如，位于 D:\Projetos\jupyter-ai-mcp-codex 的文件夹在 WSL2 中显示为 /mnt/d/Projetos/jupyter-ai-mcp-codex。

将此项目复制到 D: 盘后，打开 WSL2 并执行：

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

该脚本仅使用相对于项目本身的路径，从 uv.lock 执行 uv sync --frozen，并创建新的本地 .venv。OneDrive 或原始用户的任何路径都不会被嵌入到环境中。

如果 WSL2 发行版中尚未安装 uv，请按照 uv 的官方安装说明操作，然后重新运行该脚本。

对于大量小文件，WSL2 原生文件系统通常比 /mnt/d 更快。当优先考虑让文件在 Windows 中可见时，在 D: 中使用仍然有效且合适。

在 Windows 本地运行

在 PowerShell 中，位于此文件夹内：

.\scripts\start-local.ps1

该脚本执行 uv sync --frozen 并启动：

• JupyterLab: http://127.0.0.1:8888

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

保持终端打开。带有访问令牌的 JupyterLab URL 将显示在日志中。

使用 Docker 运行

.\scripts\start-docker.ps1

或直接：

docker compose up --build

端口仅发布到机器的回环地址。笔记本文件持久化保存在项目文件夹内的 notebooks/ 中。

要停止：

docker compose down

与 Codex 连接

此项目包含 .codex/config.toml，其中配置了服务器：

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

将位于 D: 盘的副本作为受信任项目在 Codex 中打开，并在启动 JupyterLab 后重启 Codex。该配置是项目本地的；它不会更改 ~/.codex/config.toml 中的全局配置。

如果 Codex 在 Windows 上运行而 Jupyter 在 WSL2 中运行，请先测试 http://127.0.0.1:3001/mcp。WSL2 脚本会让 MCP 在发行版内监听 0.0.0.0，WSL2 的 localhost 转发通常会使该端口在 Windows 中可访问。所提供的配置已经使用该地址。请勿在路由器上发布 3001 端口，也勿在 Windows 防火墙中打开宽泛规则。

验证

检查 MCP 是否正在监听：

Test-NetConnection 127.0.0.1 -Port 3001

预期结果是 TcpTestSucceeded : True。然后在 Codex 中，要求它使用 Jupyter MCP 的工具读取或执行 notebooks/verificacao.ipynb。

在 WSL2 中，等效的验证是：

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

MCP 端点可能返回需要有效的 MCP 请求；这仍然确认 HTTP 服务器可访问。Jupyter 日志应显示 MCP server started on port 3001。