Jupyter Notebook MCP Server (for Cursor)

Name: Jupyter Notebook MCP Server (for Cursor)
Author: jbeno

ローカル

github.comメモリ・ナレッジ16151 週間前に更新

リポジトリ公式サイト

Jupyter Notebook MCP Server (for Cursor) について

Jupyter Notebook MCP Server は、Cursor 内の AI エージェントが .ipynb ファイルのセルを読み書きできるようにする MCP サーバーです。nbformat でノートブックの構造を操作し、操作対象はユーザーが指定したディレクトリに制限されます。Cursor 向けに作られていますが、VS Code や Claude Code でも設定できます。

主な機能

01セルの読み取り、追加、編集、削除、移動
02セルの検索とノートブックのアウトライン生成
03出力のクリアとセル出力の編集
04nbconvert による Python、HTML などへのエクスポート
05stdio、Streamable HTTP、SSE のトランスポート対応

活用シーン

01Cursor のエージェントがチャットの指示に応じてセルを修正
02SFTP を使いリモート SSH サーバー上のノートブックを編集
03ノートブックを Python スクリプトや HTML 文書として出力

MCP 対応

MCP サーバーとして、notebook_read、notebook_edit_cell、notebook_export など複数のノートブック操作ツールを MCP クライアントに公開します。

#jupyter #mcp #jupyter-notebook #ipynb #cursor #mcp-server #mcp-tools

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

インストール方法は未掲載です

このサーバーのパッケージやリモートエンドポイントはまだ取得できていません。プロジェクトの README の手順に従ってください。

リポジトリ

ツール

ツール一覧はまだ取得されていません

ローカルサーバーのツールはマシン上で起動して初めて取得できます。メンテナーはまだツール一覧を提供していません。

詳細

Jupyter Notebook MCP サーバー（Cursor 向け）

このディレクトリには、AI エージェントが Cursor 内で Jupyter Notebook（.ipynb）ファイルを操作できるようにする Model Context Protocol（MCP）サーバーが含まれています。これは、Cursor の制限を克服するために作成されました。バージョン 0.50.5 の時点では、Agent モードで、AI チャットペインのダイアログに応じてモデルがノートブックやノートブックのセルを編集できませんでした。このサーバーは、ノートブックのセルを直接操作できる MCP ツール一式をエージェントに提供します。

Cursor の制限を克服するために設計されていますが、この MCP サーバーに Cursor 固有のものは、設定手順以外にはありません。VS Code（Insiders）や Claude Code、あるいは MCP を活用できる任意のモデル／エージェント向けにも簡単に設定できます。なお、VS Code（Insiders）は現在、Jupyter Notebook をかなり適切にサポートしています。

この MCP サーバーは、ノートブックの構造を安全に操作するために nbformat ライブラリを使用し、ユーザーが定義したディレクトリ内に操作を制限してセキュリティを確保します。また、ノートブックを Python スクリプトや HTML などのさまざまな形式にエクスポートできるよう、nbconvert も使用します。サーバーは、ノートブックの整合性を保ち、不正な変更を防ぐクリーンな API を通じて、すべてのノートブック操作を処理します。

動画による解説

Notebook MCP Server 0.3.0 アップデート（YouTube）

0.3.0 リリースの更新内容と新しいツールの概要
FastMCP のアップグレードとストリーミング可能な HTTP トランスポート
リモート SSH サーバー上の Jupyter Notebook を編集するための SFTP サポート
課題 (#2、#4、#5) の解決と既知の課題 (#1、#3)

Notebook MCP Server の概要（YouTube）

Cursor でノートブックを直接編集する際の現在の制限
Notebook MCP Server のインストールと設定
ノートブックを一から作成（例：2 分以内で特異値分解のチュートリアルを作成）
さまざまな編集ツール（セルの編集、分割、複製）の実演
ノートブックのメタデータの読み取り
ノートブックを Python にエクスポート

機能

以下の MCP ツールを公開します（notebook_mcp サーバーに登録されています）。

notebook_create：新しい空のノートブックファイルを作成します。
notebook_delete：既存のノートブックファイルを削除します。
notebook_rename：ノートブックファイルの名前を変更するか、別のパスに移動します。
notebook_read：ノートブック全体を読み取り、その構造を辞書として返します。
notebook_read_cell：指定したセルのソースコンテンツを読み取ります。
notebook_add_cell：指定したインデックスの後に新しいコードセルまたは Markdown セルを追加します。
notebook_edit_cell：指定したセルのソースコンテンツを置き換えます。
notebook_delete_cell：指定したセルを削除します。
notebook_change_cell_type：セルの種類（code、markdown、raw）を変更します。
notebook_duplicate_cell：セルを複数回複製します（デフォルト：1 回）。
notebook_get_cell_count：セルの合計数を返します。
notebook_read_metadata：ノートブックのトップレベルメタデータを読み取ります。
notebook_edit_metadata：ノートブックのトップレベルメタデータを更新します。
notebook_read_cell_metadata：指定したセルのメタデータを読み取ります。
notebook_read_cell_output：指定したコードセルの出力リストを読み取ります。
notebook_edit_cell_metadata：指定したセルのメタデータを更新します。
notebook_clear_cell_outputs：指定したセルの出力と実行回数をクリアします。
notebook_clear_all_outputs：すべてのコードセルの出力と実行回数をクリアします。
notebook_move_cell：セルを別の位置に移動します。
notebook_split_cell：指定した行番号でセルを 2 つに分割します。
notebook_merge_cells：セルを直後のセルと結合します。
notebook_validate：nbformat スキーマに照らしてノートブックの構造を検証します。
notebook_get_info：一般情報（セル数、メタデータ、カーネル、言語情報）を取得します。
notebook_export：nbconvert を使用してノートブックを別の形式（例：python、html）にエクスポートします。注： PDF など一部のエクスポート形式に必要な要件については、以下の「外部依存関係」を参照してください。
notebook_get_outline：エージェントが大きなノートブック内を移動しやすいように、主要な見出しや関数、行数とともにセル番号を示すアウトラインを作成します。
notebook_search：セルをキーワードで検索し、一致したセルと前後の抜粋を表示します。これにより、何かの変更を依頼されたときに、どのセルを読み取る／編集すればよいかをエージェントが把握できます。
notebook_edit_cell_output：セルの出力を直接操作し、設定できます。
notebook_bulk_add_cells：複数のセルを 1 回の操作でノートブックに追加します。
notebook_get_server_path_context：サーバーのパス設定（allowed_roots、OS のパス形式、SFTP のステータス、プロジェクトディレクトリの検証、パス構築のガイダンス）に関する詳細情報を提供します。

要件

このプロジェクトでは、すべての機能を利用するために Python パッケージへの依存関係に加えて、外部システムへの依存関係が必要になる場合があります。

Python の依存関係

Python のバージョン： 3.10+
コア： mcp>=0.1.0、nbformat>=5.0、nbconvert>=6.0、ipython、jupyter_core、paramiko>=2.8.0、fastmcp>=2.7.0,<2.11、pydantic>=2.0.0,<2.12.0、uvicorn>=0.20.0、starlette>=0.25.0。これらは cursor-notebook-mcp のインストール時に自動的にインストールされ、すべてのトランスポートモード（stdio、Streamable HTTP、SSE）に対応します。
オプション — 開発／テスト： pytest>=7.0、pytest-asyncio>=0.18、pytest-cov、pytest-timeout>=2.0.0、coveralls。ソースチェックアウトから pip install -e ".[dev]" を実行してインストールします。

外部システム依存関係（任意）

以下は Python パッケージではありません。特定の機能を動作させるには、システムに個別にインストールする必要があります。

Pandoc： 多くの HTML 以外の形式（PDF の中間処理を含む）へのエクスポートで、nbconvert が必要とします。Pandoc のインストール手順を参照してください。
LaTeX（XeLaTeX を推奨）： ノートブックを PDF に直接エクスポートする際（notebook_exportでexport_format="pdf"を指定したときに使用される--to pdfオプション）、nbconvertが必要とします。TeX のインストールを参照してください。

これらの外部依存関係がない場合、notebook_exportツールは、それらに依存する形式（PDF など）へのエクスポート時に失敗することがあります。これらの機能を使用する予定がある場合は、必ずインストールしてください。

インストール

PyPI から

標準のインストールコマンドを実行すると、stdio、Streamable HTTP、SSE の各トランスポートモードをサポートするために必要な依存関係がすべてインストールされます。

pip を使用する場合：
```
pip install cursor-notebook-mcp
```
uv を使用する場合：
```
uv pip install cursor-notebook-mcp
```

開発用インストール（ソースから）

このリポジトリをクローンします：

git clone https://github.com/jbeno/cursor-notebook-mcp.git # またはフォーク
cd cursor-notebook-mcp

仮想環境を作成して有効化します（推奨）：

# Python の venv を使用
python -m venv .venv
source .venv/bin/activate  # Windows では `.venv\Scripts\activate` を使用

# または uv を使用（インストールされている場合）
# uv venv
# source .venv/bin/activate # Windows では `.venv\Scripts\activate` を使用

すべての任意の依存関係とともに、編集可能モードでインストールします：

pip を使用する場合：

# テスト用の依存関係とともに、パッケージを編集可能モードでインストールします。
pip install -e ".[dev]"

# テスト用の追加依存関係なしで編集可能モードにインストールする場合：
# pip install -e .

uv を使用する場合：

# テスト用の依存関係とともに、パッケージを編集可能モードでインストールします。
uv pip install -e ".[dev]"

# テスト用の追加依存関係なしで編集可能モードにインストールする場合：
# uv pip install -e .

サーバーの設定と Cursor との連携

このセクションでは、選択したトランスポートプロトコルに応じて、cursor-notebook-mcpサーバーを実行し、Cursor で使用するための設定方法を説明します。

1. Streamable HTTP トランスポート（推奨）

Streamable HTTP では、サーバープロセスを手動で実行し、Cursor はネットワーク経由でサーバーに接続します。Cursor を使用するほとんどの構成では、この方法を推奨します。

A. サーバーの実行（手動での起動が必要）

まず、パッケージがインストールされていること（例：pip install cursor-notebook-mcpまたはuv pip install cursor-notebook-mcp）、ソースから実行する場合は仮想環境が有効になっていることを確認してください。

インストール済みのスクリプトを使用する場合：

cursor-notebook-mcp --transport streamable-http --allow-root /path/to/your/notebooks --host 127.0.0.1 --port 8080

ソースチェックアウトから実行する場合（依存関係がインストールされていることを確認してください。例：pip install -e .またはuv pip install -e .。テストツールも必要な場合は.[dev]を指定します）：
```
python -m cursor_notebook_mcp.server --transport streamable-http --allow-root /path/to/your/notebooks --host 127.0.0.1 --port 8080
```
/path/to/your/notebooksは、サーバーにアクセスさせるディレクトリの実際のパスに置き換えてください。

B. Cursor の`mcp.json`設定

Cursor Settings > MCP > Add new global MCP server に移動します。または、~/.cursor/mcp.json（グローバル）または.cursor/mcp.json（プロジェクト固有）ファイルを作成または更新します：

{
  "mcpServers": {
    "notebook_mcp": {
      "url": "http://127.0.0.1:8080/mcp"
    }
  }
}

注：host、port、パス（FastMCPのストリーマブル HTTP のデフォルトは/mcp）を適宜調整してください。Cursor が接続を試みる前に、サーバーが実行されている必要があります。

2. SSE トランスポート（レガシーの Web／ネットワーク）

SSE は現在レガシーのトランスポートと見なされていますが、引き続きサポートされています。新しい環境では、Streamable HTTP が推奨されます。SSE を使う場合も、サーバープロセスを手動で実行します。

A. サーバーの実行（手動での起動が必要）

パッケージがインストールされていること（例：pip install cursor-notebook-mcp または uv pip install cursor-notebook-mcp）を確認してください。ソースから実行する場合は、仮想環境が有効になっていることも確認してください。

インストール済みのスクリプトを使用する場合：

cursor-notebook-mcp --transport sse --allow-root /path/to/your/notebooks --host 127.0.0.1 --port 8080

ソースチェックアウトから実行する場合：

python -m cursor_notebook_mcp.server --transport sse --allow-root /path/to/your/notebooks --host 127.0.0.1 --port 8080

B. Cursor の `mcp.json` 設定

Cursor Settings > MCP > Add new global MCP server に移動してください。または、~/.cursor/mcp.json（グローバル）か .cursor/mcp.json（プロジェクト固有）ファイルを作成または更新してください。

{
  "mcpServers": {
    "notebook_mcp": {
      "url": "http://127.0.0.1:8081/sse"
    }
  }
}

注：FastMCP の sse トランスポートは、ハンドシェイクに /sse を使用します。Cursor が接続を試みる前に、サーバーを実行しておく必要があります。

3. stdio トランスポート

stdio トランスポートでは、Cursor がサーバープロセスを直接起動して管理します。Cursor との連携において、ターミナルでサーバーを手動実行する必要はありません。Cursor は標準入出力を介してサーバーと通信します。

この方法では、サーバーの起動に使用するコマンドと引数を Cursor に指定する必要があります。cursor-notebook-mcp とその依存関係がインストールされている正しい Python 環境を Cursor が使用するよう、注意してください。

オプション 1：特定の仮想環境への絶対パスを使用する（従来の `venv`／`virtualenv`）

このツール専用の venv がある場合は、この方法が確実です。

cursor-notebook-mcp スクリプトが venv の bin にある場合：

{
  "mcpServers": {
    "notebook_mcp": {
      "command": "/absolute/path/to/venv/bin/cursor-notebook-mcp",
      "args": [
        "--allow-root", "/absolute/path/to/your/notebooks"
      ]
    }
  }
}

venv の Python を使ってモジュールを実行する場合：

{
  "mcpServers": {
    "notebook_mcp": {
      "command": "/absolute/path/to/venv/bin/python",
      "args": [
        "-m", "cursor_notebook_mcp.server",
        "--allow-root", "/absolute/path/to/your/notebooks"
      ]
    }
  }
}

/absolute/path/to/venv/... と /absolute/path/to/your/notebooks は、実際のパスに置き換えてください。必要に応じて、他の cursor-notebook-mcp 引数（--log-level DEBUG など）も args リストに追加できます。

オプション 2：`uv` を使用して特定のプロジェクトの仮想環境から実行する（`uv` で管理されているプロジェクトに推奨）

この方法では、uv を使用して、指定したプロジェクトの Python 環境内で cursor-notebook-mcp を実行します。uv のプロジェクトコンテキストを明示的に定義するため、堅牢です。 uv がインストールされていることを確認してください。command フィールドに uv 実行ファイルのフルパスを指定する必要がある場合があります（macOS/Linux では which uv、Windows では where uv を実行すると確認できます）。uv --directory に指定するプロジェクトディレクトリは、uv が環境を管理しているプロジェクトのルートディレクトリである必要があります（例：uv venv で .venv が作成され、cursor-notebook-mcp がインストールされている場所）。以下の例は、~/.cursor/mcp.json（グローバル）または .cursor/mcp.json（プロジェクト固有）に使用できます。

cursor-notebook-mcp が uv 環境にインストールされたスクリプトの場合：

{
  "mcpServers": {
    "notebook_mcp": {
      "command": "uv", 
      "args": [
        "--directory", "/absolute/path/to/your/project/with/uv/venv", 
        "run", "--", 
        "cursor-notebook-mcp", 
        "--allow-root", "/absolute/path/to/your/notebooks"
      ]
    }
  }
}

python -m ... を使って uv run を実行する場合：

{
  "mcpServers": {
    "notebook_mcp": {
      "command": "uv", 
      "args": [
        "--directory", "/absolute/path/to/your/project/with/uv/venv", 
        "run", "--", 
        "python", "-m", "cursor_notebook_mcp.server",
        "--allow-root", "/absolute/path/to/your/notebooks"
      ]
    }
  }
}

注：これらの uv の例では、/absolute/path/to/your/project/with/uv/venv は、uv で管理される環境内に cursor-notebook-mcp がインストールされているプロジェクトの正しい絶対パスである必要があります。明確さと信頼性を高めるため、ノートブックの --allow-root パスも絶対パスにしてください。必要に応じて、他の cursor-notebook-mcp 引数（--log-level DEBUG や --port 8889 など）を、cursor-notebook-mcp または python -m cursor_notebook_mcp.server の args リストの末尾に追加できます。

AI のガイダンスに関する Cursor ルール

このパッケージには cursor_rules.md ファイルが含まれており、MCP サーバーを通じて Jupyter ノートブックを操作する際のエージェントの動作調整に役立ちます。これらのルールは、Markdown の書式設定、ツールの使用方法、パスの解決などに関するガイドラインを示し、一貫性のある整然としたノートブック操作を実現します。

デフォルトの動作：可視性とフィードバック

デフォルトでは、ノートブックの作成や変更時に AI の操作を確認できるよう、ルールが最適化されています。セルの追加などの操作では、AI は個別のツール呼び出しを使用する傾向があるため、ノートブックがセルごとに作成されていく様子を確認できます。これにより、十分なフィードバックが得られ、必要に応じてすぐに介入できます。ただし、この方法ではツール呼び出しが増えるため、有料の AI サービスを利用する場合はコストに影響する可能性があります。

Cursor でルールを設定する

Cursor ルールを使用するには：

Cursor を開きます
Cursor > Settings > Cursor Settings に移動します
サイドバーの「Rules」をクリックします
次のいずれかを選択できます：
- 「Project Rules」の下にある「Add new rule」をクリックして、現在のプロジェクトのみにルールを適用します
- 「User Rules」に追加して、ルールをグローバルに適用します

オプション：コスト効率モード

コスト効率をより重視し、結果が表示されるまで待つことを許容できる場合は、次のセクションをルールに追加できます：

8. **Efficiency Mode (Cost Optimization):**
   * Minimize tool calls as they incur API costs.
   * Use `notebook_bulk_add_cells` instead of multiple `notebook_add_cell` calls when adding multiple cells.
   * Use `notebook_read` to get the full notebook state instead of reading individual cells.
   * Only use `notebook_read_cell` when you need to verify a specific cell's content.
   * Batch related changes together when possible.
   * Skip verification reads if the operation is simple and unlikely to fail.

SFTP/SSH 経由でリモートノートブックを編集する

このサーバーは、SFTP（SSH File Transfer Protocol）を介してリモートサーバーに保存された Jupyter ノートブックへのアクセスと編集をサポートしています。リモートマシンへの SSH アクセスがあり、そのマシンで SFTP が有効になっていれば、ノートブックをローカルにあるかのように操作できます。

動作の仕組み

サーバーは paramiko ライブラリを使用して SSH 接続を確立し、その後 SFTP セッションを開始します。--sftp-root 引数を 1 つ以上指定すると、サーバーはこれらのリモートロケーションを内部パスにマッピングします。これらのリモートルート配下のパスに対するすべてのノートブック操作（読み取り、書き込み、一覧表示など）は、SFTP 経由で透過的に処理されます。

前提条件

リモートサーバーで SFTP が有効になっていること： リモートマシン上の SSH サーバーで、SFTP サブシステムが有効になっている必要があります。ほとんどの Linux/macOS SSH サーバーでは、標準で有効になっています。
SSH アクセス： リモートサーバーにアクセスするための有効な認証情報（ユーザー名、パスワード、SSH キーのいずれか、または複数）が必要です。
paramiko の依存関係： cursor-notebook-mcp パッケージにはコア依存関係として paramiko が含まれているため、通常は別途インストールする必要はありません。

トランスポートと認証に関する重要な注意事項

対話型認証（パスワードの入力要求、2 要素認証（2FA）／多要素認証（MFA）コード、SSH キーのパスフレーズなど）が必要な SFTP 接続では、cursor-notebook-mcp サーバーを streamable-http（推奨）や sse などのネットワークトランスポートを使って、手動で実行する必要があります。

これは、サーバーの起動時に SFTP 接続を確立しようとする際に、これらの入力要求が発生するためです。stdio トランスポート（Cursor がサーバーをバックグラウンドで起動する方式）を使用すると、これらの入力要求に応答できないため、接続は失敗する可能性が高くなります。

ネットワークトランスポートを使ってターミナルでサーバーを手動実行すると、必要なパスワード、パスフレーズ、2FA コードの入力がターミナル上で直接求められます。

SFTP コマンドライン引数

SFTP アクセスを設定するには、サーバーの起動時に次のコマンドライン引数を使用します。

--sftp-root user@host:/path/to/remote/notebooks
- リモートのノートブックディレクトリを指定します。書式は username@hostname:/absolute/path/on/server です。
- この引数を複数回使用して、複数の異なるリモートロケーションをマッピングできます。
- パスではチルダ展開（~）がサポートされています（例：user@host:~/notebooks）。
--sftp-password your_password_or_passphrase
- （任意）SSH パスワード認証用のパスワード、または暗号化された SSH 秘密鍵用のパスフレーズを指定します。
- セキュリティに関する注意： コマンドラインに認証情報を直接指定すると、セキュリティ上のリスク（シェル履歴やプロセス一覧への露出など）が生じる可能性があります。通常はこの引数を省略し、サーバー起動時の対話型入力を使用するか、可能であればパスフレーズなしの SSH エージェント／鍵ベース認証を使用するほうが安全です。
--sftp-key /path/to/your/private_key
- SSH 秘密鍵ファイルへのパスを指定します（例：~/.ssh/id_rsa）。
--sftp-port port_number
- SFTP 接続に使用する SSH ポートです。デフォルトは 22 です。
--sftp-auth-mode mode:
- SFTP の認証モードを指定します（例：auto、key、password、key+interactive）。デフォルトは auto です。
--sftp-no-agent:
- SFTP 認証で SSH エージェントを使用しないようにします。
--sftp-no-interactive:
- SFTP 認証に関するすべての対話型入力要求を無効にします。
--sftp-no-password-prompt:
- --sftp-password で指定されていない場合、パスワード／パスフレーズの入力要求をスキップします。ただし、その他の対話型入力要求（例：2FA コード）は許可されます。

SFTP 設定例

以下に、さまざまな SFTP 認証方式を使って cursor-notebook-mcp サーバーを起動する例を示します。streamable-http などのネットワークトランスポートを使用してください。

1. パスワード認証

パスワードを対話形式で入力：

cursor-notebook-mcp --transport streamable-http --host 0.0.0.0 --port 8080 \
  --sftp-root [email protected]:/home/myuser/notebooks \
  --sftp-auth-mode password

（サーバーの起動時に、myuser のパスワードを尋ねられます。）

引数でパスワードを指定（安全性は低くなります）：

cursor-notebook-mcp --transport streamable-http --host 0.0.0.0 --port 8080 \
  --sftp-root [email protected]:/home/myuser/notebooks \
  --sftp-password "MySecretP@ssw0rd" \
  --sftp-auth-mode password

2. SSH キー認証

パスフレーズなしのキー（例：~/.ssh/id_rsa）：

cursor-notebook-mcp --transport streamable-http --host 0.0.0.0 --port 8080 \
  --sftp-root [email protected]:~/project_notebooks \
  --sftp-key ~/.ssh/id_rsa \
  --sftp-auth-mode key

パスフレーズ付きのキー（対話形式で入力）：

cursor-notebook-mcp --transport streamable-http --host 0.0.0.0 --port 8080 \
  --sftp-root [email protected]:/srv/notebooks \
  --sftp-key ~/.ssh/encrypted_key \
  --sftp-auth-mode key

（encrypted_key のパスフレーズを尋ねられます。）

パスフレーズ付きのキー（引数で指定）：

cursor-notebook-mcp --transport streamable-http --host 0.0.0.0 --port 8080 \
  --sftp-root [email protected]:/data/notebooks \
  --sftp-key ~/.ssh/encrypted_key \
  --sftp-password "MyPrivateKeyPassphrase" \
  --sftp-auth-mode key

3. キーボード対話型認証（例：2FA/MFA）

サーバーがユーザー名／パスワードや2FAコードを要求：

cursor-notebook-mcp --transport streamable-http --host 0.0.0.0 --port 8080 \
  --sftp-root [email protected]:~/notebooks \
  --sftp-auth-mode interactive

4. 組み合わせ：SSH キー（パスフレーズで保護）＋キーボード対話型認証（2FA/MFA）

SSH キーがパスフレーズで暗号化されており、サーバーでもキーボード対話型認証を介した第2要素（TOTPコードなど）が必要な場合のシナリオです。

cursor-notebook-mcp --transport streamable-http --host 0.0.0.0 --port 8080 \
  --sftp-root [email protected]:~/notebooks \
  --sftp-key ~/.ssh/your_encrypted_rsa_key \
  --sftp-auth-mode key+interactive

（サーバーの起動時に、まず your_encrypted_rsa_key のパスフレーズを尋ねられます。パスフレーズを正しく入力した後、サーバーでさらに対話型認証が必要な場合は、2FAコードなどの入力を求められます。）

5. 組み合わせ：パスワード＋キーボード対話型認証（例：パスワードの後に2FAコード）

cursor-notebook-mcp --transport streamable-http --host 0.0.0.0 --port 8080 \
  --sftp-root [email protected]:~/notebooks \
  --sftp-auth-mode password+interactive

（パスワードを入力した後、サーバーが必要とする場合は2FAコードを尋ねられます。）

6. SSH エージェントの使用

デフォルト（--sftp-auth-mode auto または key）では、サーバーは実行中の SSH エージェントを使用しようとします。キーがエージェントに読み込まれている場合、--sftp-key やキーのパスフレーズを指定する --sftp-password は不要なことがあります。

2FA を使用するエージェント（2FAコードのみキーボード対話型認証）：

cursor-notebook-mcp --transport streamable-http --host 0.0.0.0 --port 8080 \
  --sftp-root [email protected]:~/notebooks \
  --sftp-auth-mode auto  # 明示的に指定する場合は key+interactive
  # 任意：エージェントがキーを処理する場合は --sftp-no-password-prompt を指定します。ただし、2FAプロンプトは別途表示されます

（キーがエージェントに読み込まれていることを前提とします。キー認証後にサーバーが要求する場合は、2FAコードの入力を求められます。）

複数のリモートルート

--sftp-root は複数回指定して、異なるパスに接続できます。認証方式に互換性があれば、別々のサーバーにも接続できます（また、サーバーがルートごとの認証情報を指定する引数に対応している場合は、各ルートに個別の認証情報を指定できますが、現在は対応していません。そのため、パスワードやキーのファイルを指定した場合、すべての接続で同じ共通の認証情報が使用されます）。

cursor-notebook-mcp --transport streamable-http --host 0.0.0.0 --port 8080 \
  --sftp-root [email protected]:/projects/alpha \
  --sftp-root [email protected]:~/personal_notebooks \
  --sftp-key ~/.ssh/id_serverA \
  --sftp-auth-mode key

パスの処理

チルダの展開： --sftp-root 内の ~/my_notebooks のようなリモートパスは、リモートサーバー上のユーザーのホームディレクトリに展開されます。
内部マッピング： サーバーは、内部処理のためにこれらのリモート SFTP パスを一時的なローカル風の表現にマッピングします。Cursor のユーザーとして操作する際は、元のリモート形式のパス（例：[email protected]:/home/myuser/notebooks/MyNotebook.ipynb）を使用します。
notebook_get_server_path_context によるコンテキストの把握： サーバーとやり取りする AI エージェントにとって、notebook_get_server_path_context ツールは特に便利です。設定されているすべてのルート（ローカルと SFTP）、サーバーの OS のパス形式、パスの構築および解決方法に関するガイダンスを提供します。これにより、AI は指定された SFTP パスがユーザーの現在のプロジェクトディレクトリ（ローカルの場合）とどのように関連するかを理解し、ローカルとリモートのパスが混在するユーザーの指示を正しく解釈できます。

SFTP ルートを設定してサーバーを起動すると、--allow-root（ローカルファイルの場合）または設定済みの --sftp-root の範囲内であれば、ローカルのノートブックと同じように、Cursor で notebook_mcp ツールを使ってこれらのリモートパス上のノートブックを操作できます。

ログ

サーバーは、トラブルシューティングと監視に役立つよう、操作内容をログに記録します。

デフォルトのログ保存先： デフォルトでは、ログファイルは ~/.cursor_notebook_mcp/server.log に保存されます（.cursor_notebook_mcp ディレクトリはユーザーのホームディレクトリに作成されます）。
ログディレクトリの指定： --log-dir コマンドライン引数を使って、ログファイルの保存先として別のディレクトリを指定できます。例：cursor-notebook-mcp --allow-root /path/to/notebooks --log-dir /custom/log/path
ログレベル： --log-level 引数を使って、ログの詳細度を制御できます。デフォルトのログレベルは INFO です。その他に DEBUG、WARNING、ERROR、CRITICAL を指定できます。DEBUG に設定すると、処理済みのものも含め、すべての例外について完全なスタックトレースを含む詳細な出力が表示されるため、開発や詳細なトラブルシューティングに特に役立ちます。

コマンドライン引数

サーバーは次のコマンドライン引数を受け付けます。

--allow-root：--sftp-root が指定されていない場合は必須です。複数回指定できます。ローカルのノートブックが許可されるディレクトリの絶対パスです。
--log-dir：ログファイルを保存するディレクトリです。デフォルトは ~/.cursor_notebook_mcp です。
--log-level：ログレベルを設定します：DEBUG、INFO、WARNING、ERROR、CRITICAL。デフォルトは INFO です。
--max-cell-source-size：セルのソースコンテンツに許可される最大サイズ（バイト単位）です。デフォルトは 10 MiB です。
--max-cell-output-size：セルの出力コンテンツに許可される最大サイズ（バイト単位）です。デフォルトは 10 MiB です。
--transport：使用するトランスポートの種類です：stdio、streamable-http、または sse。デフォルトは stdio です。Web では streamable-http を推奨します。sse は非推奨の代替手段です。
--host：Streamable HTTP または SSE サーバーをバインドするホストです。--transport=streamable-http または --transport=sse の場合のみ使用されます。デフォルトは 127.0.0.1 です。
--port：Streamable HTTP または SSE サーバーをバインドするポートです。--transport=streamable-http または --transport=sse の場合のみ使用されます。デフォルトは 8080 です。
--sftp-root user@host:/path/to/remote/notebooks：
- SFTP 経由でリモートのノートブックディレクトリを指定します。複数回指定できます。
- 詳しい使い方と認証については、「SFTP/SSH 経由でのリモートノートブックの編集」セクションを参照してください。
--sftp-password your_password_or_passphrase：
- （任意ですが、セキュリティ上推奨されません）SSH 認証用のパスワード、または暗号化された SSH 秘密鍵用のパスフレーズを指定します。通常はこの引数を省略し、必要に応じて対話型プロンプトで認証情報を入力する方が安全です。
--sftp-key /path/to/your/private_key：
- SFTP 認証に使用する SSH 秘密鍵ファイルのパスです。
--sftp-port port_number：
- SFTP 接続に使用する SSH ポートです。デフォルトは 22 です。
--sftp-auth-mode mode：
- SFTP の認証モードです（例：auto、key、password、key+interactive）。デフォルトは auto です。
--sftp-no-agent：
- SFTP 認証で SSH エージェントを使用しないようにします。
--sftp-no-interactive：
- SFTP 認証に関するすべての対話型プロンプトを無効にします。
--sftp-no-password-prompt：
- --sftp-password で指定されていない場合も、パスワード／パスフレーズのプロンプトをスキップします。ただし、ほかの対話型プロンプト（例：2FA コード）は許可されます。

セキュリティ

ワークスペースのルートの強制： サーバーの起動時に、コマンドライン引数 --allow-root が必要です。この引数で指定されたディレクトリの外にあるノートブックファイルに対する操作は拒否されます。これは重要なセキュリティ境界です。
パスの処理： サーバーは os.path.realpath を使用してパスを解決し、読み取りまたは書き込みを行う前に、許可されたルートと照合します。
SFTP 認証のセキュリティ： SFTP 経由でリモートノートブックに接続する場合は、ネットワークトランスポート（streamable-http または sse）の使用を強く推奨します。これにより、サーバーはパスワード、SSH キーのパスフレーズ、2 要素認証（2FA）コードなどの認証情報を、ターミナルで対話形式により直接入力するよう求めることができます。この方法は、コマンドライン引数（例：--sftp-password）で機密情報を渡すよりも安全です。シェルの履歴やシステムのプロセス一覧に認証情報が残るのを防げるためです。サーバーは、こうした対話形式のプロンプトを利用して、証明書と 2FA、パスワードと 2FA などを組み合わせた多要素認証を含む、さまざまな認証フローに対応しています。
入力の検証： .ipynb 拡張子の基本的なチェックを行います。
セルのソースサイズ制限： サーバーは、メモリの過剰な使用を防ぐため、notebook_edit_cell と notebook_add_cell に渡されるソースコンテンツに最大サイズ制限を設けています（--max-cell-source-size で設定可能。デフォルトは 10 MiB）。
セルの出力サイズ制限： サーバーは、notebook_read_cell_output が返す出力のシリアライズ後の合計サイズに最大サイズ制限を設けています（--max-cell-output-size で設定可能。デフォルトは 10 MiB）。

制限事項

セルの実行には非対応： このサーバーはノートブックのセルを実行できません。nbformat ライブラリを使用して .ipynb ファイルの構造のみを操作し、Jupyter カーネルとは連携しません。セルの実行は、Cursor UI 内でカーネルを選択し、セルを実行して手動で行う必要があります。

問題

バグを発見した場合、機能の追加を希望する場合、またはその他の問題が発生した場合は、既存の Issue を確認するか、GitHub の Issue トラッカーに新しい Issue を登録してください。

既知の問題

現在把握されている問題については、GitHub の Issues タブを確認してください。

UI の更新に関する問題： セルの分割や結合などのノートブック操作がファイル上では成功していても、Cursor UI に更新された内容が正しく表示されないことがあります。その場合は、次の操作を試してください。
- ノートブックファイルを閉じて、もう一度開きます。
- ファイルを保存します。「Revert（元に戻す）」または「Overwrite（上書き）」を求められる場合があります。「Revert（元に戻す）」を選択して、実際のファイルの内容を再読み込みします。
チェックポイントには非対応： エージェントがサードパーティ製 MCP ツールを使って編集しても、AI チャットの履歴には「Restore Checkpoint」ボタン付きのチェックポイントとして記録されません。対策として、次の方法があります。
- git を使ってこまめにコミットし、ロールバックできるようにします。
- 重要な節目ごとに、作業内容のコピーを手動で作成します。
ファイルや行のコンテキストなし： Cursor は、他のファイルのように Jupyter ノートブックのコンテキストを自動的に共有しません。他のファイル（Python、Markdown）では、現在のファイルと行番号が AI エージェントに共有されます。しかし、ノートブックではコンテキストが共有されません。理想的には、セルとそのセル内の行番号も共有されるべきです。これを補うには、次の方法があります。
- 編集したいセル、関数、セクションが分かっている場合は、できるだけ具体的に伝えてください。
- エージェントは notebook_get_outline を使用して、ノートブックの大まかなアウトラインを取得できます。これにより、重要なクラス、関数、Markdown の見出しが含まれるセルを特定しやすくなります。
- エージェントは notebook_search を使用して、キーワード、クラス、関数を含むセルを特定できます。

Issue の提出

新しい Issue を提出するには：

jbeno/cursor-notebook-mcp Issues ページにアクセスします。
「New Issue」をクリックします。
次の情報を記載します：
- 問題または機能リクエストの明確な説明。
- 問題を再現する手順（該当する場合）。
- 期待される動作と実際の動作。
- お使いの環境の詳細（OS、Python のバージョン、cursor-notebook-mcp のバージョンなど）。
- 関連するエラーメッセージやログ。
- 使用しているモデルとクライアント／バージョン（AI とのやり取りに関係する場合）。

コントリビューション

Jupyter Notebook MCP Server の改善へのコントリビューションを歓迎します！

コントリビューションをご希望の場合は、リポジトリをフォークし、変更用のブランチを作成してから、jbeno/cursor-notebook-mcp の main ブランチに Pull Request（PR）を作成してください。

変更には次の内容を含めてください：

新機能に関連するユニットテスト。
使用方法に影響する変更や機能追加がある場合は、ドキュメント（README.md、CHANGELOG.md）の更新。
既存のコードスタイルの遵守。

PR を提出する前に、テストスクリプト（./run_tests.sh または .\run_tests.ps1）を実行して、すべてのテストが成功することを確認してください。

大規模な変更に関する議論： 大幅な変更や新機能については、まず Issue を作成して提案内容を議論し、プロジェクトの目標に沿っていることを確認することをおすすめします。

開発環境のセットアップ

まず、リポジトリをクローンして仮想環境をセットアップします。次に、すべての開発用およびテスト用依存関係を含めて、パッケージを編集可能モードでインストールします：

pip を使用する場合：

# プロジェクトのルートディレクトリから実行
python -m venv .venv
source .venv/bin/activate  # Windows では .venv\Scripts\activate を使用
pip install -e ".[dev]"

uv を使用する場合：

# プロジェクトのルートディレクトリから実行
uv venv
source .venv/bin/activate  # Windows では .venv\Scripts\activate を使用
uv pip install -e ".[dev]"

ユニットテストの実行

このプロジェクトでは、ユニットテストに pytest を使用します。テストファイルは tests/ ディレクトリにあります。新しいテストを追加する場合は、既存の命名規則（例：test_*.py）に従い、このディレクトリに配置してください。

テストを実行するには、用意されているラッパースクリプトを使用します。これらのスクリプトはテストファイルを個別に実行します。これにより、このプロジェクトのすべてのテストファイルに対して pytest を直接実行した場合に、非同期処理や SFTP テストなどで発生することがあるハングの問題を防ぎやすくなります。

Linux/macOS の場合： 環境変数が正しく設定されるよう、ラッパースクリプトを使用します。
```
./run_tests.sh 
# 特定のテストを実行する場合：
# ./run_tests.sh tests/test_notebook_tools.py
```

Windows の場合： PowerShell ラッパースクリプトを使用します。

.\run_tests.ps1
# 特定のテストを実行する場合：
# .\run_tests.ps1 tests/test_notebook_tools.py

コードカバレッジ

ラッパースクリプト（run_tests.sh または run_tests.ps1）を使用してテストを実行すると、pytest-cov によってコードカバレッジが自動的に計算されます。

詳細なカバレッジレポートは Coveralls で確認できます。現在のカバレッジ状況は、この README の上部にあるバッジ、または https://coveralls.io/github/jbeno/cursor-notebook-mcp?branch=main から直接確認できます。

AI 主導のテスト計画（`test_plan.md`）

自動ユニットテストに加えて、このリポジトリには test_plan.md ファイルが含まれています。このドキュメントでは、Agent Mode の Cursor や、notebook_mcp ツールにアクセスできる同様の会話型 AI などの AI エージェントが実行することを想定した、シナリオベースのテストを一連の手順としてまとめています。

使用するには、AI エージェントに「test_plan.md に記載されたテスト計画を実行してください」と指示します。この計画では、基本的な編集から SFTP アクセスやメタデータの変更まで、幅広いノートブック操作を扱っており、現実的な複数ステップのワークフローでツールの実用性と正確性を検証できます。テスト計画には、さまざまなオペレーティングシステム（macOS/Linux または Windows）に対応した手順が記載されています。

ライセンス

このプロジェクトは、Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License の下でライセンスされています。詳細については、LICENSE ファイルをご覧ください。

この作品は、Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License の下でライセンスされています。

作者

このプロジェクトは Jim Beno が作成し、メンテナンスしています - [email protected]

Markdown 対応

ログインしてコメント

基本情報

ライセンス: NOASSERTION
作者: jbeno
言語: python
トランスポート: stdio
掲載日: 2025年4月20日
最終更新: 51 週間前

問題を報告

MCP は初めてですか？

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

入門ガイドを読む

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。

Jupyter Notebook MCP Server (for Cursor)

Jupyter Notebook MCP Server (for Cursor) について

主な機能

活用シーン

MCP 対応

設定

ツール

詳細

Jupyter Notebook MCP サーバー（Cursor 向け）

最新バージョン

動画による解説

Notebook MCP Server 0.3.0 アップデート（YouTube）

Notebook MCP Server の概要（YouTube）

機能

要件

Python の依存関係

外部システム依存関係（任意）

インストール

PyPI から

開発用インストール（ソースから）

サーバーの設定と Cursor との連携

1. Streamable HTTP トランスポート（推奨）

A. サーバーの実行（手動での起動が必要）

B. Cursor のmcp.json設定

2. SSE トランスポート（レガシーの Web／ネットワーク）

A. サーバーの実行（手動での起動が必要）

B. Cursor の mcp.json 設定

3. stdio トランスポート

オプション 1：特定の仮想環境への絶対パスを使用する（従来の venv／virtualenv）

オプション 2：uv を使用して特定のプロジェクトの仮想環境から実行する（uv で管理されているプロジェクトに推奨）

AI のガイダンスに関する Cursor ルール

デフォルトの動作：可視性とフィードバック

Cursor でルールを設定する

オプション：コスト効率モード

SFTP/SSH 経由でリモートノートブックを編集する

動作の仕組み

前提条件

トランスポートと認証に関する重要な注意事項

SFTP コマンドライン引数

SFTP 設定例

1. パスワード認証

2. SSH キー認証

3. キーボード対話型認証（例：2FA/MFA）

4. 組み合わせ：SSH キー（パスフレーズで保護）＋キーボード対話型認証（2FA/MFA）

5. 組み合わせ：パスワード＋キーボード対話型認証（例：パスワードの後に2FAコード）

6. SSH エージェントの使用

複数のリモートルート

パスの処理

ログ

コマンドライン引数

セキュリティ

制限事項

問題

既知の問題

Issue の提出

コントリビューション

開発環境のセットアップ

ユニットテストの実行

コードカバレッジ

AI 主導のテスト計画（test_plan.md）

ライセンス

作者

コメント

MCP は初めてですか？

MCP（Model Context Protocol）とは？

MCP サーバーとクライアントの違いは？

ローカルとリモート、どちらを選ぶべき？

Claude や Cursor にサーバーを導入するには？

掲載プロジェクトは審査されていますか？「認証済み」とは？

自分のプロジェクトが掲載されています。どう申請できますか？

B. Cursor の`mcp.json`設定

B. Cursor の `mcp.json` 設定

オプション 1：特定の仮想環境への絶対パスを使用する（従来の `venv`／`virtualenv`）

オプション 2：`uv` を使用して特定のプロジェクトの仮想環境から実行する（`uv` で管理されているプロジェクトに推奨）

AI 主導のテスト計画（`test_plan.md`）