Jupyter VS Code MCP

VS Code 拡張機能。Jupyter ノートブックの操作を プレーンな HTTP 経由の MCP ツール として公開します。あらゆる AI コーディングエージェントに対応するポータブルな URL を 1 つ提供します。絶対パスも node コマンドも stdio 配線も不要です。

任意の MCP クライアントをその URL に向けるだけで、エージェントはライブなエディタセッション内のノートブックを参照・編集・実行・デバッグできます。あなたが見ているのと同じセルを見て、ノートブックが使用しているのと同じカーネル(ローカル またはリモート — Colab も含む)と通信し、すべての操作が実際の VS Code UI に反映されます。

機能

安定したセルハンドルによるノートブック編集

• すべてのセルは、#NB-xxxxxxxx という単一の統一スキームで識別され、標準の nbformat 4.5 の cell id フィールドに永続化されます。編集、他のセルの挿入/削除、インデックスのずれ、保存/再オープン、拡張機能のリロードを経ても維持され、ファイルを別のマシンにコピーしても維持されます。

• 削除後の ID の再利用は行われません。新しいセルには常に新しいランダムな ID が付与されます。jupyter_get_summary は ID を持たないセル(UI で手動作成されたセルなど)に ID を割り当てるため、報告されたすべてのハンドルをすぐに再利用できます。

• インデックスは(サマリー、ソース、実行範囲、出力の)すべての場所で 0 始まり です。混在する規約はありません。

ノンブロッキング実行制御

• jupyter_run_cells は実行を開始してすぐに戻ります。jupyter_wait_until_idle でポーリングするか、jupyter_get_status でスナップショットを取得できます。闇雲なスリープも、長いセルでの MCP タイムアウトもありません。

• カーネル準備完了ガード: 停止中/存在しないカーネルに対して実行すると、ハングアップする代わりに実行可能なヒントを返します。

• jupyter_interrupt_kernel はすべての変数を保持したまま現在の実行を中断します。

カーネルインテリジェンス (Copilot グレード)

• jupyter_get_variables — 型を認識した変数レポート: DataFrame/Series は {shape, columns[:8], head(2)}、ndarray は {shape, dtype}、コンテナは length 付き、スカラーは短い repr で表します。利用可能な場合は公式の Jupyter 変数ビュー API を使用し、それ以外の場合は実行カウントに一切触れないサイレントなカーネルプローブを使用します。オプションのドキュメントシンボルフィルタリングは、シンボルが実際に利用可能な場合にのみ内部ノイズを隠します。

• jupyter_get_pip_packages — アクティブなカーネル環境からの環境インベントリ(名前 + バージョン)

• jupyter_install_packages — pip はカーネル自身のインタープリタ内で実行されるため、パッケージはノートブックが実際に使用するランタイムにインストールされます。Colab のようなリモート VM も含まれ、ローカルホストにはインストールされません。バージョン指定と --upgrade をサポートし、その後各指定が解決されることを検証します。また、成功したふりをせず、正直な失敗(pip の実際の出力の末尾付き)を報告します。

• jupyter_get_status は、古いメタデータを信頼せず、ライブなカーネルに実際の Python バージョン/プラットフォームを問い合わせます。

• jupyter_select_kernel は、カーネルがアクティブでない場合に VS Code のネイティブなカーネルピッカーを開きます。

ネットワーク専用 MCP トランスポート

• プレーンな JSON レスポンスを持つ Streamable HTTP (MCP 仕様 2025-11-25)。最小限のクライアントは curl だけで動作します。

• エンドポイント: /mcp(レガシー /sse も)、GET /health は死活監視 + バージョンプローブ用。

• 複数の同時エージェントセッションをサポート。セッションは実行中のポート変更後も維持されます。

正直なレポート

エラーにはコンテキストと次のステップのヒントが含まれます。カーネルが見つからない → 起動ガイダンス、古い ID → サマリーで更新、pip インストール失敗 → 実際の pip エラー末尾、ビジーなカーネル → 黙って空の結果を返す代わりに明示的な延期メモ。

Related MCP server: Jupyter MCP Server

ツール

安定したセル ID

すべてのセルには、標準の nbformat 4.5 の cell id フィールドに書き込まれるランダムな永続 ID (#NB-xxxxxxxx) が付与されます。これは、プラットフォーム自体が読み取り、保存/読み込みで往復させるのと同じスロットです。この ID は、位置の変更、コンテンツの編集、隣接セルの挿入/削除、再オープンのサイクルによる影響を受けません。インデックスよりも ID を優先してください。ID を確認するには jupyter_get_summary を呼び出します(ツール外で作成されたセルに欠けている ID もバックフィルされます)。

8 桁の 16 進数のみの入力 (abcd1234) は #NB-abcd1234 の短縮形として受け入れられます。

互換性のあるエージェント

HTTP を話す任意の MCP クライアントで動作します。一般的な設定:

Claude Code, Cursor, Windsurf, Cline, Copilot:

{
  "mcpServers": {
    "jupyter-vscode-mcp": {
      "url": "http://localhost:9123/mcp"
    }
  }
}

OpenCode, Kilo Code:

{
  "mcp": {
    "jupyter-vscode-mcp": {
      "type": "remote",
      "url": "http://localhost:9123/mcp",
      "enabled": true
    }
  }
}

コマンドパレットから "Jupyter VS Code MCP: Show MCP Configuration" を実行 → エージェントを選択 → スニペットがクリップボードにコピーされます。

インストールと実行

最新の .vsix を リリース からダウンロードし、次に:

code --install-extension jupyter-vscode-mcp-<version>.vsix

1. 任意の .ipynb を開きます — サーバーは 127.0.0.1:9123 で自動起動します(ステータスバーに状態が表示され、クリックで切り替え)。

2. 上記の URL 設定をエージェントに追加します。

3. いつでも死活を確認できます: curl http://localhost:9123/health。

設定: jupyter-vscode-mcp.mcpPort(デフォルト 9123、ホット適用)、jupyter-vscode-mcp.autoStart(デフォルト true)。

推奨ワークフロー

jupyter_list_open_notebooks   → pick notebook
jupyter_get_summary           → stable #NB-* IDs, exec state        (0-based)
jupyter_get_cell_source       → read only what you need
jupyter_edit_cell             → IDs stay valid after edits
jupyter_run_cells             → starts async, returns immediately
jupyter_wait_until_idle       → blocks until done (or poll get_status)
jupyter_get_outputs           → inline short text, artifact files for big/binary
jupyter_get_variables         → inspect kernel state after runs

アーキテクチャ

AI agent ──HTTP/JSON-RPC──▶ VS Code extension (in-process http server :9123)
                                 │ vscode.* APIs + ms-toolsai.jupyter public API
                                 ▼
                     notebook cells, outputs, kernel status

カーネルとのやり取りは、文書化された ms-toolsai.jupyter 公開 API (kernel.executeCode、割り込み/再起動コマンド、変数/pip 一覧コマンド)とコマンドのフォールバックを使用します。実行追跡は workspace.onDidChangeNotebookDocument に依存しています。

開発

npm install
npm run compile      # typecheck
npm run lint
npm run build        # esbuild bundle
npm run smoke        # local protocol smoke test (vscode stubbed)
npx @vscode/vsce package

参考文献

• Model Context Protocol — Streamable HTTP トランスポート、仕様 2025-11-25

• microsoft/vscode-copilot-chat (MIT) — 変数の要約、切り詰め上限、シンボルフィルタリングのパターン

• SMARK OpenCode IDE Bridge — Jupyter 公開 API によるカーネル事前チェック、割り込み/再起動コマンドのフォールバック、イベントベースの完了追跡

• kriss-spy/opencode-jupyter — 元となった HTTP ブリッジのコンセプト

ライセンス

MIT