このサーバーにより、互換性のある AI アシスタント (Cursor や Claude Desktop など) がローカル マシン上の Jupyter Notebook ファイル (.ipynb) と対話できるようになります。
📋 前提条件
始める前に、以下がインストールされていることを確認してください。
- **Python:**バージョン 3.10 以上。
uv : Astral社の高速Pythonパッケージインストーラー兼仮想環境マネージャー。まだインストールしていない場合はインストールしてください。# On macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# On Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# IMPORTANT: Add uv to your PATH if prompted by the installer
# For macOS/Linux (bash/zsh), add to your ~/.zshrc or ~/.bashrc:
# export PATH="$HOME/.local/bin:$PATH"
# Then restart your shell or run `source ~/.zshrc` (or equivalent)
fastmcp CLI (オプション、Claude Desktop fastmcp installの場合): Claude Desktop にfastmcp installメソッドを使用する予定の場合は、 fastmcpコマンドが利用可能である必要があります。# Using uv
uv pip install fastmcp
# Or using pipx (recommended for CLI tools)
pipx install fastmcp
🔧 セットアップ
- リポジトリをクローンします。
git clone https://github.com/UsamaK98/python-notebook-mcp.git # Or your fork/local path
cd python-notebook-mcp
- セットアップ方法を選択してください:
- **オプション A: 自動セットアップ (推奨)**プロジェクトのルート ディレクトリ (
cdで移動したディレクトリ) から、OS に適したスクリプトを実行します。- macOS / Linux:
# Make script executable (if needed)
chmod +x ./install_unix.sh
# Run the script
bash ./install_unix.sh
- Windows (PowerShell):GXP5 これらのスクリプトは、
.venvを作成し、依存関係をインストールし、MCP クライアント構成に必要な正確なパスを出力します。
- オプション B: 手動セットアップ手動で制御したい場合、またはスクリプトで問題が発生した場合は、次の手順に従ってください。
- 仮想環境の作成とアクティブ化:
# Create the environment (e.g., named .venv)
uv venv
# Activate the environment
# On macOS/Linux (bash/zsh):
source .venv/bin/activate
# On Windows (Command Prompt):
# .venv\Scripts\activate.bat
# On Windows (PowerShell):
# .venv\Scripts\Activate.ps1
(.venv)または同様のものが表示されます) - 依存関係をインストールします:
# Make sure your venv is active
uv pip install -r requirements.txt
▶️ サーバーの実行
手動セットアップを使用した場合は、仮想環境 ( .venv ) がアクティブ化されていることを確認してください。
方法 1: 直接実行 (カーソル、一般的な用途に推奨)
この方法では、 uv runを使用して、現在の Python 環境 (依存関係がインストールされている必要があります) でサーバー スクリプトを直接実行します。
- サーバーを実行します。
# From the python-notebook-mcp directory
uv run python server.py
- クライアント設定（
mcp.json ）： MCPクライアント（例：Cursor）が接続できるように設定します。クライアントのMCP設定ファイル（例：ワークスペース内の.cursor/mcp.json ）を作成または編集します。テンプレート（推奨）:{
"mcpServers": {
"jupyter": {
// Use the absolute path to the Python executable inside your .venv
"command": "/full/absolute/path/to/python-notebook-mcp/.venv/bin/python", // macOS/Linux
// "command": "C:\\full\\absolute\\path\\to\\python-notebook-mcp\\.venv\\Scripts\\python.exe", // Windows
"args": [
// Absolute path to the server script
"/full/absolute/path/to/python-notebook-mcp/server.py"
],
"autoApprove": ["initialize_workspace"] // Optional: Auto-approve certain safe tools
}
}
}
❓ Pythonへのフルパスが必要な理由とは？ CursorのようなGUIアプリケーションは、ターミナルと同じPATH環境を継承しない場合があります。.venv .venv内にPythonインタープリターへの正確なパスを指定することで、サーバーが正しい環境と依存関係で実行されるようになります。⚠️重要：プレースホルダーパスをシステム上の実際の絶対パスに置き換えてください。
方法 2: Claude デスクトップ統合 ( fastmcp install )
この方法では、 fastmcpツールを使用してサーバー専用の隔離された環境を作成し、Claude Desktopに登録します。fastmcp fastmcp install環境作成を処理するため、通常、この方法では.venvファイルを手動でアクティベートする必要はありません。
- Claude 用のサーバーをインストールします。
# From the python-notebook-mcp directory
fastmcp install server.py --name "Jupyter Notebook MCP"
fastmcp install 、バックグラウンドでuvを使用して環境を作成し、 requirements.txtから依存関係をインストールします。- サーバーはClaude Desktopの開発者設定に表示され、そこで有効化できます。fastmcp
fastmcp installを使用する場合、通常、 claude_desktop_config.json手動で編集する必要はありません。
📘 使用方法
キーコンセプト: ワークスペースの初期化
サーバーの実行方法に関わらず、AIアシスタントから最初に行うべき アクションはワークスペースの初期化です。これにより、プロジェクトファイルとノートブックの場所がサーバーに通知されます。
# Example tool call from the client (syntax may vary)
initialize_workspace(directory="/full/absolute/path/to/your/project_folder")
⚠️ ノートブックが格納されているディレクトリへの絶対パスを指定する必要があります。相対パスや.のようなパスは受け付けられません。サーバーがパスを確認し、既存のノートブックがあれば一覧表示します。
コアオペレーション
ワークスペースが初期化されると、利用可能なツールを使用できるようになります。
# List notebooks
list_notebooks()
# Create a new notebook
create_notebook(filepath="analysis/new_analysis.ipynb", title="My New Analysis")
# Add a code cell to the notebook
add_cell(filepath="analysis/new_analysis.ipynb", content="import pandas as pd\ndf = pd.DataFrame({'col1': [1, 2], 'col2': [3, 4]})\ndf.head()", cell_type="code")
# Read the first cell (index 0)
read_cell(filepath="analysis/new_analysis.ipynb", cell_index=0)
# Edit the second cell (index 1)
edit_cell(filepath="analysis/new_analysis.ipynb", cell_index=1, content="# This is updated markdown")
# Read the output of the second cell (index 1) after execution (if any)
read_cell_output(filepath="analysis/new_analysis.ipynb", cell_index=1)
# Read the entire notebook structure
read_notebook(filepath="analysis/new_analysis.ipynb")
🛠️ 利用可能なツール
| 道具 | 説明 |
|---|
initialize_workspace | **必須の最初のステップ。**ワークスペースの絶対パスを設定します。 |
list_notebooks | ワークスペース ディレクトリ内で見つかったすべての.ipynbファイルを一覧表示します。 |
create_notebook | 存在しない場合は、新しい空の Jupyter ノートブックを作成します。 |
read_notebook | ノートブックの全体的な構造とコンテンツを読み取ります。 |
read_cell | インデックスによって特定のセルの内容とメタデータを読み取ります。 |
edit_cell | 既存のセルのソース コンテンツをインデックスによって変更します。 |
add_cell | 特定のインデックスまたは末尾に新しいコード セルまたはマークダウン セルを追加します。 |
read_notebook_outputs | ノートブック内のすべてのコード セルからすべての出力を読み取ります。 |
read_cell_output | インデックスによって特定のコード セルの出力を読み取ります。 |
🧪 開発とデバッグ
サーバー自体をデバッグする必要がある場合:
- 直接実行:
uv run python server.pyを使用して、ターミナル出力でエラーや print ステートメントを確認します。 - FastMCP 開発モード: MCP インスペクターを使用した対話型テストの場合:
# Make sure fastmcp is installed in your environment
# uv pip install fastmcp
uv run fastmcp dev server.py
📄 ライセンス
このプロジェクトは MIT ライセンスに基づいてライセンスされています - 詳細についてはLICENSEファイルを参照してください。