Robust new jupyter server

Jupyter MCP サーバー

1 つのライブ Jupyter ノートブックを安全に読み取り、編集し、実行するための、用途を絞った Model Context Protocol サーバーです。

実装は意図的に小規模に保たれています。ノートブック 1 つ、カーネル 1 つ、標準の stdio トランスポートで構成されます。各操作はセッションロックを共有し、コードは 1 回だけ追加・実行されます。また、最初に表示される出力ではなく、カーネルの最終実行応答を待ちます。

公開する機能

MCP プリミティブ	名前	目的
ツール	add_markdown_cell	Markdown セルを 1 つ追加し、確認する
ツール	add_execute_code_cell	コードセルを 1 回だけ追加・実行し、構造化出力を返す
ツール	read_notebook_content	一貫性のあるノートブックスナップショットを読み取る
ツール	kernel_restart	現在のカーネル／セッションを安全に置き換える
リソース	jupyter://notebook	読み取り専用のノートブック JSON
プロンプト	analyse_notebook	ノートブックを変更する前に分析する

HTML、画像、JSON、ストリーム、結果、トレースバックのデータは構造化出力モデルに保持されます。実行エラー、タイムアウト、不明な結果は、成功を示す文字列ではなく MCP エラーとして返されます。

要件

• Python 3.10 以降（3.12 を推奨）
• リアルタイムコラボレーションを有効にした JupyterLab サーバー
• uv（推奨）または pip

ローカルでのセットアップ

サーバーと開発ツールをインストールします。

uv sync --extra dev

有効なノートブックドキュメントを作成します（空のファイルはノートブックではありません）。

uv run python -c "import nbformat; nbformat.write(nbformat.v4.new_notebook(), 'notebook.ipynb')"

別の環境またはターミナルで、Jupyter をインストールして起動します。

uv run --with jupyterlab --with jupyter-collaboration \
  jupyter lab \
  --port 8888 \
  --ServerApp.port_retries 0 \
  --ServerApp.root_dir . \
  --IdentityProvider.token MY_TOKEN \
  --no-browser

MCP サーバーを実行します。

NOTEBOOK_PATH=notebook.ipynb \
SERVER_URL=http://localhost:8888 \
TOKEN=MY_TOKEN \
uv run jupyter-mcp

サーバーは初回使用時に Jupyter 接続を開くため、パッケージのインポートや MCP ツールの一覧表示に、Jupyter の起動は必要ありません。

MCP クライアントの設定

ローカルの stdio サーバーを起動するクライアントには、次の形式を使用し、リポジトリのパスをチェックアウト先に置き換えてください。

{
  "mcpServers": {
    "jupyter": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/jupyter_mcp_server_kshitij",
        "run",
        "jupyter-mcp"
      ],
      "env": {
        "NOTEBOOK_PATH": "notebook.ipynb",
        "SERVER_URL": "http://localhost:8888",
        "TOKEN": "MY_TOKEN"
      }
    }
  }
}

設定

変数	デフォルト	説明
NOTEBOOK_PATH	notebook.ipynb	Jupyter サーバールートからの相対パス
SERVER_URL	http://localhost:8888	Jupyter サーバーの URL
TOKEN	空	Jupyter 認証トークン。実行時に設定します
CONNECTION_TIMEOUT_SECONDS	15	起動、クリーンアップ、中断のタイムアウト
EXECUTION_TIMEOUT_SECONDS	30	カーネルの最大実行時間
CONNECTION_ATTEMPTS	2	変更前の接続試行回数

接続の再試行は、変更を行う前に限って実施されます。実行が始まった後に切断が発生すると、「結果不明」という明示的なエラーが返され、セルが自動的に再実行されることはありません。

Docker

非 root イメージをビルドして実行します。トークンにはイメージのデフォルト値が設定されていないため、実行時に指定する必要があります。

docker build -f dockerfile -t jupyter-mcp .
docker run --rm -i \
  -e NOTEBOOK_PATH=notebook.ipynb \
  -e SERVER_URL=http://host.docker.internal:8888 \
  -e TOKEN=MY_TOKEN \
  jupyter-mcp

開発

uv run pytest
uv run ruff check .

ユニットテストでは、ノートブックとカーネルのモッククライアントを使用するため、稼働中の Jupyter サーバーは必要ありません。エンドツーエンドで確認するには、上記のように Jupyter を起動し、MCP クライアントまたは MCP Inspector を使ってツールを試してください。

安全性とライフサイクルの保証

• モジュールのインポート時にネットワーク I/O は発生しません。
• MCP のライフスパン終了処理では、正常終了時も異常終了時も、ノートブッククライアントとカーネルクライアントの両方を閉じます。
• asyncio.Lock により、ノートブックの変更、実行、読み取り、再起動の並行処理を防止します。
• ノートブッククライアントの公開シーケンス／エクスポート API を使用し、非公開の _doc と _ycells の内部にはアクセスしません。
• カーネルエラーとタイムアウトは MCP エラーになります。タイムアウトしたカーネルは中断され、不確かな状態のセッションは再利用前に破棄されます。
• 標準の stdio トランスポートのみが有効です。無言で raw-TCP にフォールバックすることはありません。