🚀 Jupyter MCP Server

🚀 Jupyter MCP Server

AI エージェントと Jupyter ノートブックを連携させ、リアルタイムのコード実行、可視化の生成、高度な画像抽出機能を実現する、包括的な Model Context Protocol（MCP）サーバーです。

🎯 このプロジェクトについて

このプロジェクトは、Datalayer, Inc. が開発したオリジナルの Jupyter MCP Server をフォークし、機能を強化したものです。Jupyter と Model Context Protocol エコシステムの連携における基盤となる取り組みを行った Datalayer チームに、心より感謝いたします。

このフォークでの主な強化点：

• ドキュメントとセットアッププロセスの改善
• エラー処理と堅牢性の強化
• 設定例の追加
• インストールと設定の効率化
• 依存関係と互換性の更新

🌟 主な機能

🎯 Jupyter とのリアルタイム連携

• ライブコード実行：WebSocket 接続を通じて Python コードをリアルタイムに実行
• カーネル管理：カーネルの自動作成、ライフサイクル管理、クリーンアップ
• セッションの永続化：複数の操作にわたって状態を維持

🖼️ 高度な画像抽出

• 複数の形式をサポート：matplotlib、seaborn、plotly から PNG および JPEG 画像を抽出
• Base64 エンコード：AI 処理ですぐに使える画像データ
• 包括的な出力処理：テキスト、画像、エラー、実行結果に対応

📚 包括的なノートブック管理

• ファイル操作：複数のノートブックの作成、削除、切り替え
• セル操作：CRUD 操作によるセルの追加、変更、移動、削除
• コンテンツ管理：Markdown セルとコードセルの両方をサポート

🛡️ エンタープライズ対応のセキュリティ

• スマートな XSRF 処理：トークンを自動検出して管理
• 認証サポート：トークン認証を使用する Jupyter サーバーと互換
• エラー復旧：接続の問題に対する適切なフォールバック

🏗️ アーキテクチャ

graph TD
    A[AI Agent/Claude] --> B[MCP Server]
    B --> C[Jupyter Server API]
    B --> D[WebSocket Channels]
    C --> E[Kernel Management]
    D --> F[Real-time Execution]
    F --> G[Output Capture]
    G --> H[Image Extraction]
    G --> I[Text Processing]
    B --> J[Notebook Files]

🛠️ 18 種類の包括的なツール

📝 セルコンテンツ管理

• add_execute_code_cell - Python コードを実行し、リアルタイムで出力
• add_markdown_cell - 書式付きのドキュメントを追加
• modify_cell - 既存のセルコンテンツを編集
• change_cell_type - Markdown セルとコードセルを相互に変換

🖼️ 出力の抽出

• get_cell_image_output - Base64 エンコードされた画像（PNG/JPEG）を抽出
• get_cell_text_output - エラーやトレースバックを含むすべてのテキスト出力を取得

🗂️ ノートブックのファイル操作

• create_notebook - 新しいノートブックファイルを作成
• delete_notebook - ノートブックファイルを安全に削除
• switch_notebook - アクティブなノートブックを切り替え
• list_notebooks - 利用可能なノートブックを一覧表示

🔍 データの確認

• list_cells - プレビュー付きで全セルの概要を表示
• read_cell - 特定のセルの全コンテンツを読み取り
• get_notebook_info - ノートブックの包括的なメタデータを取得

ツールの全ドキュメントを見る →

🚀 クイックスタート

前提条件

• Python 3.11+
• Jupyter Notebook
• Claude Desktop または互換性のある MCP クライアント

インストール

1. リポジトリをクローン

   git clone https://github.com/JosephLin11/jupyter-mcp-server.git
   cd jupyter-mcp-server
   

2. 依存関係をインストール

   pip install -r requirements.txt
   

3. Jupyter Server を起動

   ./scripts/start_jupyter.sh
   

4. Claude Desktop を設定 claude_desktop_config.json に追加します：

   {
     "mcpServers": {
       "jupyter": {
         "command": "python",
         "args": ["/path/to/your/jupyter-mcp-server/src/jupyter_mcp_server.py"]
       }
     }
   }
   

   💡 ヒント：python3 scripts/get_claude_config.py を実行すると、現在のパスに基づいた正しい設定を生成できます！

💡 ユースケースの例

📊 データ可視化パイプライン

# 1. Create and execute visualization code
add_execute_code_cell(cell_content="""
import matplotlib.pyplot as plt
import numpy as np
import seaborn as sns

# Generate sample data
data = np.random.normal(0, 1, 1000)

# Create beautiful visualization
plt.figure(figsize=(12, 8))
plt.subplot(2, 2, 1)
plt.hist(data, bins=50, alpha=0.7, color='skyblue')
plt.title('Distribution Analysis')

plt.subplot(2, 2, 2)
sns.boxplot(y=data)
plt.title('Box Plot Analysis')

plt.tight_layout()
plt.show()
""")

# 2. Extract the generated image
get_cell_image_output(cell_index=0)

🧪 科学計算

# 3D surface visualization
add_execute_code_cell(cell_content="""
from mpl_toolkits.mplot3d import Axes3D
import numpy as np
import matplotlib.pyplot as plt

fig = plt.figure(figsize=(12, 9))
ax = fig.add_subplot(111, projection='3d')

# Create mesh
x = np.linspace(-5, 5, 100)
y = np.linspace(-5, 5, 100)
X, Y = np.meshgrid(x, y)
Z = np.sin(np.sqrt(X**2 + Y**2))

# Render surface
surface = ax.plot_surface(X, Y, Z, cmap='plasma', alpha=0.9)
ax.set_title('3D Mathematical Function')
plt.colorbar(surface)
plt.show()
""")

# Extract 3D visualization
get_cell_image_output(cell_index=1)

🏆 技術的な特長

高度な WebSocket 実装

• Jupyter カーネルとのリアルタイム双方向通信
• 包括的なメッセージタイプ処理（execute_result、display_data、stream、error）
• 自動再接続とフォールバック機構

スマートな出力処理

• Base64 エンコードによる複数形式の画像抽出（PNG、JPEG）
• メタデータを保持した構造化出力の取得
• 完全なトレースバックをサポートするエラー処理

堅牢なセキュリティモデル

• XSRF トークンの自動検出と管理
• 複数の認証エンドポイントをサポート
• さまざまな Jupyter 構成に対応する適切な縮退動作

エンタープライズグレードのエラー処理

• 設定可能なログレベルによる包括的なロギング
• 信頼性を高めるフォールバック実行モード
• リソースのクリーンアップと接続管理

📊 代替手段との比較

機能	この実装	jjsantos01 MCP	Cursor MCP
利用可能なツール	🏆 18 個のツール	10 個のツール	8～10 個のツール
画像抽出	🏆 PNG + JPEG	PNG のみ	なし
セットアップの複雑さ	🏆 自動	ブラウザーの手動初期化	CLI 引数
バージョンサポート	🏆 すべての Jupyter バージョン	Jupyter 6.x のみ	バージョンに依存しない
リアルタイム実行	🏆 WebSocket + HTTP	WebSocket ブリッジ	ファイルのみ
セキュリティ処理	🏆 XSRF 自動処理	基本	強化

🧪 テスト

包括的なテストスイートを実行します：

# Test image extraction capabilities
python tests/test_image_extraction.py

# Test notebook operations  
python tests/test_notebook_save.py

📁 プロジェクト構成

jupyter-mcp-server/
├── src/
│   └── jupyter_mcp_server.py      # Main MCP server implementation
├── notebooks/                     # 📓 All Jupyter notebooks are created here
│   └── mcp_notebook.ipynb         # Default notebook for MCP operations
├── tests/
│   ├── test_image_extraction.py   # Image extraction tests
│   └── test_notebook_save.py      # Notebook operation tests
├── scripts/
│   ├── start_jupyter.sh           # Jupyter server startup script
│   └── get_claude_config.py       # Claude configuration generator
├── examples/
│   ├── claude_desktop_config.json # Example configuration
│   ├── mcp_notebook.ipynb         # Example notebook
│   └── new_notebook.ipynb         # Sample notebook
├── docs/
│   ├── MCP_TOOLS_SUMMARY.md       # Complete tool reference
│   ├── SETUP.md                   # Setup guide
│   └── IMAGE_EXTRACTION_README.md # Image extraction guide
├── requirements.txt               # Python dependencies
├── pyproject.toml                 # Project configuration
└── README.md                      # Project documentation

🤝 貢献

貢献を歓迎します！以下の手順に従ってください：

1. リポジトリをフォークします
2. フィーチャーブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更をコミットします（git commit -m 'Add amazing feature'）
4. ブランチにプッシュします（git push origin feature/amazing-feature）
5. プルリクエストを作成します

📄 ライセンス

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

🌟 謝辞

• オリジナルの開発：基盤となる Jupyter MCP Server を作成した Datalayer, Inc. に感謝します
• Model Context Protocol エコシステムから着想を得ています
• 堅牢な Jupyter Server API を基盤としています
• さまざまな MCP 実装のアイデアを取り入れて強化されています
• オープンソースコミュニティに特別な感謝を申し上げます

📧 お問い合わせ

Joseph Lin - GitHub

プロジェクトリンク：https://github.com/JosephLin11/jupyter-mcp-server

オリジナルプロジェクト：https://github.com/datalayer/jupyter-mcp-server

---