Python notebook

このサーバーを使うと、互換性のある AI アシスタント（Cursor や Claude Desktop など）が、ローカルマシン上の Jupyter Notebook ファイル（.ipynb）を操作できます。

📋 前提条件

始める前に、次のソフトウェアがインストールされていることを確認してください。

1. Python： バージョン 3.10 以降。
2. uv： Astral が提供する高速な Python パッケージインストーラー兼仮想環境マネージャーです。まだインストールしていない場合は、次の手順でインストールしてください。

   # macOS / Linux の場合
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # Windows（PowerShell）の場合
   powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
   
   # 重要：インストーラーに指示された場合は、uv を PATH に追加してください
   # macOS/Linux（bash/zsh）の場合は、~/.zshrc または ~/.bashrc に追加します：
   # export PATH="$HOME/.local/bin:$PATH"
   # その後、シェルを再起動するか `source ~/.zshrc`（または同等のコマンド）を実行します
   

3. fastmcp CLI（オプション、Claude Desktop の fastmcp install 用）： Claude Desktop で fastmcp install を使う場合は、fastmcp コマンドを利用できるようにする必要があります。

   # uv を使う場合
   uv pip install fastmcp
   
   # または pipx を使う場合（CLI ツールに推奨）
   pipx install fastmcp
   

🔧 セットアップ

1. リポジトリをクローンする：

   git clone https://github.com/UsamaK98/python-notebook-mcp.git # またはフォーク／ローカルのパス
   cd python-notebook-mcp
   

2. セットアップ方法を選択する：

   • オプション A：自動セットアップ（推奨） プロジェクトのルートディレクトリ（先ほど cd で移動した場所）から、お使いの OS に対応するスクリプトを実行します。

     • macOS / Linux：

       # 必要に応じてスクリプトを実行可能にする
       chmod +x ./install_unix.sh
       # スクリプトを実行する
       bash ./install_unix.sh
       

     • Windows（PowerShell）：

       # 先にPowerShellの実行ポリシーを変更する必要がある場合があります
       # Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
       .\install_windows.ps1
       

     これらのスクリプトは .venv を作成して依存関係をインストールし、MCP クライアントの設定に必要な正確なパスを出力します。

   • オプション B：手動セットアップ 手動で制御したい場合や、スクリプトで問題が発生した場合は、次の手順に従ってください。

     1. 仮想環境を作成して有効化する：

        # 環境を作成する（例：.venvという名前）
        uv venv
        
        # 環境を有効化する
        # macOS/Linux（bash/zsh）の場合：
        source .venv/bin/activate
        # Windows（コマンドプロンプト）の場合：
        # .venv\Scripts\activate.bat
        # Windows（PowerShell）の場合：
        # .venv\Scripts\Activate.ps1
        

        （シェルプロンプトの先頭に (.venv) などが表示されます）
     2. 依存関係をインストールする：

        # venvが有効になっていることを確認する
        uv pip install -r requirements.txt
        

▶️ サーバーの実行

手動でセットアップした場合は、仮想環境（.venv）が有効になっていることを確認してください。

方法 1：直接実行（Cursorでの使用、一般的な用途に推奨）

この方法では uv run を使い、現在の Python 環境（依存関係がインストール済みのはずです）でサーバースクリプトを直接実行します。

1. サーバーを実行する：

   # python-notebook-mcpディレクトリから実行する
   uv run python server.py
   

   サーバーが起動し、未初期化のワークスペースディレクトリを含むステータスメッセージが表示されます。

2. クライアントの設定（mcp.json）： MCP クライアント（例：Cursor）を設定して接続します。クライアントのMCP設定ファイル（例：ワークスペース内の .cursor/mcp.json）を作成または編集してください。

   テンプレート（推奨）：

   {
     "mcpServers": {
       "jupyter": {
         // .venv内のPython実行ファイルへの絶対パスを使用する
         "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": [
             // サーバースクリプトへの絶対パス
             "/full/absolute/path/to/python-notebook-mcp/server.py"
           ],
         "autoApprove": ["initialize_workspace"] // 任意：安全なツールを自動承認する
       }
     }
   }
   

   ❓ Pythonへのフルパスが必要なのはなぜですか？ CursorなどのGUIアプリケーションでは、ターミナルと同じ PATH 環境が引き継がれない場合があります。.venv 内のPythonインタープリターへの正確なパスを指定すると、サーバーが正しい環境と依存関係で実行されます。 ⚠️ IMPORTANT： プレースホルダーのパスを、お使いのシステム上の実際の絶対パスに置き換えてください。

方法 2：Claude Desktop との統合（fastmcp install）

この方法では、fastmcp ツールを使用してサーバー専用の分離された環境を作成し、Claude Desktop に登録します。fastmcp install が環境の作成を処理するため、この方法では通常、.venv を手動で有効化する必要はありません。

1. Claude 用にサーバーをインストールする：

   # python-notebook-mcp ディレクトリから実行
   fastmcp install server.py --name "Jupyter Notebook MCP"
   

   • fastmcp install は、内部で uv を使用して環境を作成し、requirements.txt から依存関係をインストールします。
   • サーバーは Claude Desktop の開発者設定に表示され、そこで有効にできます。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 Inspector を使って対話的にテストするには、次のコマンドを実行します。

  # 環境に fastmcp がインストールされていることを確認してください
  # uv pip install fastmcp
  uv run fastmcp dev server.py
  

📄 ライセンス

このプロジェクトは MIT ライセンスの下で公開されています。詳細については、LICENSE ファイルを参照してください。