JupyterMCP - Jupyter Notebook Model Context Protocol Integration

JupyterMCP - Jupyter Notebook Model Context Protocol 連携

JupyterMCP は、Model Context Protocol（MCP）を通じて Jupyter Notebook と Claude AI を接続し、Claude が Jupyter Notebook と直接やり取りして制御できるようにします。この連携により、AI を活用したコード実行、データ分析、可視化などが可能になります。

⚠️ 互換性に関する警告

このツールは Jupyter Notebook バージョン 6.x とのみ互換性があります。

以下では動作しません。

• Jupyter Lab
• Jupyter Notebook v7.x
• VS Code Notebooks
• Google Colab
• その他のノートブックインターフェース

機能

• 双方向通信：WebSocket ベースのサーバーを通じて Claude AI を Jupyter Notebook に接続します
• セル操作：ノートブックのセルを挿入、実行、管理します
• ノートブック管理：ノートブックを保存し、ノートブック情報を取得します
• セルの実行：特定のセルを実行するか、ノートブック内のすべてのセルを実行します
• 出力の取得：テキストの制限オプションを指定して、実行したセルの出力内容を取得します

コンポーネント

システムは、次の3つの主要コンポーネントで構成されています。

1. WebSocket サーバー（jupyter_ws_server.py）：Jupyter 内に WebSocket サーバーをセットアップし、ノートブックと外部クライアント間の通信を仲介します
2. クライアント JavaScript（client.js）：ノートブック内で実行され、操作（セルの挿入、コードの実行など）を処理します
3. MCP サーバー（jupyter_mcp_server.py）：Model Context Protocol を実装し、WebSocket サーバーに接続します

インストール

前提条件

• Python 3.12 以降（おそらく古いバージョンでも動作しますが、テストされていません）
• uv パッケージマネージャー
• Claude AI デスクトップアプリケーション

uv のインストール

Mac の場合：

brew install uv

Windows の場合（PowerShell）：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

その他のプラットフォームについては、uv のインストールガイドを参照してください。

セットアップ

1. このリポジトリをコンピューターにクローンまたはダウンロードします。

   git clone https://github.com/jjsantos01/jupyter-notebook-mcp.git
   

2. 必要なパッケージを含む仮想環境を作成し、jupyter-mcp カーネルをインストールします。これにより、既存の Jupyter インストール環境で認識されるようになります。

   uv run python -m ipykernel install --name jupyter-mcp
   

3. （任意）分析に使用する追加の Python パッケージをインストールします。

   uv pip install seaborn
   

4. Claude デスクトップアプリとの連携を設定します。 Claude > Settings > Developer > Edit Config > claude_desktop_config.json に移動し、次の内容を追加します。

      {
       "mcpServers": {
           "jupyter": {
               "command": "uv",
               "args": [
                   "--directory",
                   "/ABSOLUTE/PATH/TO/PARENT/REPO/FOLDER/src",
                   "run",
                   "jupyter_mcp_server.py"
               ]
           }
       }
   }
   

   /ABSOLUTE/PATH/TO/ を、システム上の src フォルダーへの実際のパスに置き換えます。例：

   • Windows："C:\\Users\\MyUser\\GitHub\\jupyter-notebook-mcp\\src\\"
   • Mac：/Users/MyUser/GitHub/jupyter-notebook-mcp/src/

   Claude をすでに開いている場合は、File > Exit を選択してから、もう一度起動してください。

使い方

接続の開始

1. Jupyter Notebook（バージョン 6.x）サーバーを起動します。

   uv run jupyter nbclassic
   

2. 新しい Jupyter Notebook を作成し、jupyter-mcp カーネルを選択します。kernel -> change kernel -> jupyter-mcp

3. ノートブックのセルで次のコードを実行し、WebSocket サーバーを初期化します。

   import sys
   sys.path.append('/path/to/jupyter-notebook-mcp/src')  # Add the path to where the scripts are located
   
   from jupyter_ws_server import setup_jupyter_mcp_integration
   
   # Start the WebSocket server inside Jupyter
   server, port = setup_jupyter_mcp_integration()
   

   ここで '/path/to/jupyter-notebook-mcp/src' を、システム上の src フォルダーへのパスに置き換えてください。例：

   • Windows："C:\\Users\\MyUser\\GitHub\\jupyter-notebook-mcp\\src\\"
   • Mac：/Users/MyUser/GitHub/jupyter-notebook-mcp/src/

   

4. MCP を有効にして Claude デスクトップアプリを起動します。

Claude での使用

接続すると、Claude は以下のツールを利用できるようになります。

• ping - サーバーの接続状態を確認します
• insert_and_execute_cell - 指定した位置にセルを挿入して実行します
• save_notebook - 現在の Jupyter ノートブックを保存します
• get_cells_info - ノートブック内のすべてのセルの情報を取得します
• get_notebook_info - 現在のノートブックの情報を取得します
• run_cell - インデックスを指定してセルを実行します
• run_all_cells - ノートブック内のすべてのセルを実行します
• get_cell_text_output - 指定したセルの出力内容を取得します
• get_image_output - 指定したセルの画像出力を取得します
• edit_cell_content - 既存のセルの内容を編集します
• set_slideshow_type- セルのスライドショーの種類を設定します

⚠️ 免責事項

これは実験的なプロジェクトであり、注意して使用してください。このツールはコンピューター上で任意の Python コードを実行するため、慎重に使用しないとデータが変更または削除される可能性があります。重要なプロジェクトやデータは必ずバックアップしてください。

プロンプトの例

Claude にノートブックの操作を依頼します。

Python の例

サンプルノートブックと動画デモを確認できます。

You have access to a Jupyter Notebook server.

I need to create a presentation about Python's Seaborn library.  
The content is as follows:

- What is Seaborn?
- Long vs. Wide data format
- Advantages of Seaborn over Matplotlib
- Commonly used Seaborn functions
- Live demonstration (comparison of Seaborn vs. Matplotlib)
  - Bar plot
  - Line plot
  - Scatter plot

For each concept, I want the main explanations provided in markdown cells, followed by one or more Python code cells demonstrating its usage. Keep the text concise—the cells shouldn't exceed 10 lines each.

Use appropriate slideshow types for each cell to make the presentation visually appealing.

会話の全内容はこちら

Stata の例

この例では、オープンソースではない Stata ソフトウェア（v17 以降）が必要です。すでに Stata をお持ちの場合は、stata-setup パッケージをインストールしてください。

uv pip install stata-setup

次に、ノートブックの冒頭に以下を追加してください。

import stata_setup
stata_setup.config('your_stata_installation_directory', 'your_stata_edition')

サンプルノートブックと動画デモを確認できます。

この演習は、John Robert Warren 教授のウェブページから引用しています。

You have access to a Jupyter Notebook server. By default it runs Python, but you can run Stata (v18) code in this server using the %%stata magic, for example:

%%stata
display "hello world"

Run the available tools to solve the exercise, execute the code, and interpret the results.

**EXERCISE:**

In this exercise, you will use data from the American Community Survey (ACS). The ACS is a product of the U.S. Census Bureau and involves interviewing millions of Americans each year. For an introduction to the ACS, visit the ACS website (here).

For this exercise, I have created a data file containing two variables collected from respondents of the 2010 ACS who lived in one of two metropolitan areas: Minneapolis/St Paul and Duluth/Superior. The two variables are: (1) People's poverty status and (2) the time it takes people to commute to work.

Use STATA syntax files you already have (from the first assignment or class examples) and modify them to accomplish the following goals.

1. Read the data file (`"./stata_assignment_2.dat"`) for this assignment into STATA.
2. Be sure to declare "zero" as a missing value for `TRANTIME`, the commuting time variable.
3. Create a new dichotomous poverty variable that equals "1" if a person's income-to-poverty-line ratio (`POVRATIO`) is less than 100, and "0" otherwise; see the bottom of the assignment for an example of how to do this in STATA.
4. Separately for Minneapolis/St Paul and Duluth/Superior, produce:
   - a histogram of the commuting time (`TRANTIME`) variable.
   - measures of central tendency and spread for commuting time.
   - a frequency distribution for the poverty status (0 vs 1) variable.
5. Separately for Minneapolis/St Paul and Duluth/Superior, use STATA code to produce:
   - a 95% confidence interval for the mean commuting time.
   - a 95% confidence interval for the proportion of people who are poor. See below for an example of how to do this in STATA.

Use the results from step #4 above to:

6. Separately for Minneapolis/St Paul and Duluth/Superior, manually calculate:
   - a 95% confidence interval for the mean commuting time.
   - a 95% confidence interval for the proportion of people who are poor.
7. Confirm that your answers from steps #5 and #6 match.

Based on the results above, answer this question:

8. How do you interpret the confidence intervals calculated in steps #5 and #6 above?

9. Finally, create a do file (.do) with the all the Stata code and the answers as comments.

---

**DESCRIPTION OF VARIABLES IN "STATA ASSIGNMENT 2.DAT"**

**METAREAD** (Column 4-7)  
Metropolitan Area  
- `2240`: Duluth-Superior, MN/WI  
- `5120`: Minneapolis-St. Paul, MN  

**POVRATIO** (Column 18-20)  
Ratio of person's income to the poverty threshold:  
- `<100`: Below Poverty Line  
- `100`: At Poverty Line  
- `>100`: Above Poverty Line  

**TRANTIME** (Column 21-23)  
Travel time to work  
- `0`: Zero minutes  
- `1`: 1 Minute  
- etc.

会話の全内容はこちら

外部クライアントでのテスト

付属の外部クライアントを使用すると、Claude Desktop を使わずに機能をテストできます。

uv run python src/jupyter_ws_external_client.py

これにより、利用可能な一部の機能をテストするためのインタラクティブなメニューが表示されます。

すべてのコマンドを自動テストするには、次のようにします。

uv run python src/jupyter_ws_external_client.py --batch

トラブルシューティング

• 接続の問題：接続がタイムアウトする場合、クライアントには再接続の仕組みが含まれています。WebSocket サーバーを再起動することもできます。
• セル実行の問題：セルを実行できない場合は、セルの内容が有効な Python／Markdown であることと、ノートブックのカーネルが実行中であることを確認してください。
• WebSocket ポートの競合：デフォルトのポート（8765）がすでに使用されている場合、サーバーは自動的に利用可能なポートを探します。

制限事項

• Jupyter Notebook 6.x のみをサポートしています
• セルからのテキスト出力は、デフォルトで 1500 文字までです
• 高度な Jupyter ウィジェットの操作はサポートしていません
• 一定時間操作がないと接続がタイムアウトする場合があります

ライセンス

MIT

その他の Jupyter MCP

このプロジェクトは、Jupyter 向けの以下のような MCP 統合を参考にしています。

• ihrpr
• Datalayer