Jupyter MCP Server

🚀 Jupyter_MCP_Server

JupyterMCP 實現了 Jupyter Notebook 與 Claude AI 通過 Model Context Protocol (MCP) 的集成。藉助該集成，Claude 能夠與 Jupyter 筆記本直接交互並進行控制，實現 AI 輔助的代碼執行、數據分析、可視化等功能。

🚀 快速開始

啟動連接

1. 啟動你的 Jupyter Notebook（版本 6.x）服務器：

uv run jupyter notebook

2. 打開瀏覽器訪問 http://localhost:8888，然後導航到 jupyter_mcp_server.py 筆記本。
3. 在筆記本中執行以下代碼以啟動 MCP 服務器：

from jupyter_mcp_server import start_server
start_server()

✨ 主要特性

• 雙向通信：通過基於 WebSocket 的服務器將 Claude AI 連接到 Jupyter Notebook。
• 單元格操作：可插入、執行和管理筆記本中的單元格。
• 筆記本管理：支持保存筆記本並獲取筆記本信息。
• 單元格執行：能執行特定的單元格或運行整個筆記本的所有單元格。
• 輸出獲取：可獲取已執行單元格的輸出內容，且帶有文本限制選項。

📦 安裝指南

先決條件

• Python 3.12 或更高版本（可能與舊版本兼容，但未測試）
• [uv 包管理器](/README.md#安裝 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. 創建虛擬環境並安裝所需的 packages，並安裝 jupyter-mcp 內核，以便 Jupyter 安裝程序識別：

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

3. （可選）安裝數據分析的額外 Python 包：

uv pip install seaborn

4. 配置 Claude 桌面集成： 轉到 Claude > 設置 > 開發者 > 編輯配置 > 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/，例如：

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

如果你之前已經打開了 Claude，請關閉並重新打開。

💻 使用示例

基礎用法

在連接後，Claude 將具有訪問以下工具的能力：

# 檢查服務器連通性
ping

# 在指定位置插入單元格並執行它
insert_and_execute_cell

# 保存當前 Jupyter 筆記本
save_notebook

# 獲取所有單元格的信息
get_cells_info

# 獲取當前筆記本的信息
get_notebook_info

# 按照索引運行特定的單元格
run_cell

# 運行筆記本中的所有單元格
run_all_cells

# 獲取特定單元格的輸出內容
get_cell_text_output

# 獲取特定單元格的圖像輸出
get_image_output

# 編輯現有單元格的內容
edit_cell_content

# 設置單元格的幻燈片類型
set_slideshow_type

🔧 技術細節

系統由三個主要組件組成：

1. WebSocket 服務器 (jupyter_ws_server.py)：在 Jupyter 中設置一個 WebSocket 服務器，實現筆記本與外部客戶端之間的橋樑通信。
2. 客戶 JavaScript (client.js)：運行在筆記本中以處理操作（插入單元格、執行代碼等）。
3. MCP 服務器 (jupyter_mcp_server.py)：實現 Model Context Protocol 並連接到 WebSocket 服務器。