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보다 빠른 경우가 많습니다. 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

터미널을 열어 두세요. 액세스 토큰이 포함된 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이 표시되어야 합니다.