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 と表示されるはずです。