Jupyter AI MCP para Codex

Воспроизводимый проект для запуска JupyterLab и предоставления его инструментов Codex через MCP. Зависимости Python управляются исключительно с помощью uv.

Требования

• uv

• Python 3.10 или выше (uv может установить его)

• Codex Desktop, CLI или расширение для VS Code

• Docker Desktop, только если вы выберете запуск в контейнере

Related MCP server: jupyter-interactive-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 sync --frozen на основе uv.lock и создаёт новый локальный .venv. Никакие пути OneDrive или исходного пользователя не попадают в окружение.

Если uv ещё не установлен в дистрибутиве WSL2, следуйте официальной инструкции по установке uv, а затем снова запустите скрипт.

Для лучшей производительности с большим количеством мелких файлов родная файловая система WSL2 обычно быстрее, чем /mnt/d. Использование D: остаётся допустимым и уместно, когда приоритет — сохранить файлы видимыми для Windows.

Локальный запуск в Windows

В PowerShell, внутри этой папки:

.\scripts\start-local.ps1

Скрипт выполняет uv sync --frozen и запускает:

• JupyterLab: http://127.0.0.1:8888

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

Держите терминал открытым. URL JupyterLab с токеном доступа будет показан в журнале.

Запуск с помощью Docker

.\scripts\start-docker.ps1

Или напрямую:

docker compose up --build

Порты публикуются только на loopback машины. Блокноты сохраняются в notebooks/ внутри самой папки проекта.

Для завершения:

docker compose down

Подключение к Codex

Этот проект включает .codex/config.toml с сервером:

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

Откройте копию, расположенную на диске D:, как доверенный проект в Codex и перезапустите Codex после запуска JupyterLab. Конфигурация является локальной для проекта; она не изменяет глобальную конфигурацию в ~/.codex/config.toml.

Если Codex работает в Windows, а Jupyter — в WSL2, сначала проверьте http://127.0.0.1:3001/mcp. Скрипт WSL2 заставляет MCP прослушивать 0.0.0.0 внутри дистрибутива, и проброс localhost в WSL2 обычно делает порт доступным в Windows. Предоставленная конфигурация уже использует этот адрес. Не публикуйте порт 3001 на роутере и не открывайте широкое правило в брандмауэре Windows.

Проверка

Проверьте, слушает ли MCP:

Test-NetConnection 127.0.0.1 -Port 3001

Ожидаемый результат — TcpTestSucceeded : True. Затем в Codex попросите его прочитать или выполнить notebooks/verificacao.ipynb с помощью инструментов Jupyter MCP.

В 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.