/ 目錄 / 演練場 / jupyter-mcp-server
● 社群 datalayer ⚡ 即開即用

jupyter-mcp-server

作者 datalayer · datalayer/jupyter-mcp-server

讓 Claude 即時執行與閱讀你的 Jupyter 筆記本 — 執行儲存格、查看圖表、從錯誤中復原,全部不用離開聊天視窗。

jupyter-mcp-server (Datalayer) 將 MCP 用戶端連接到執行中的 JupyterLab/Jupyter Server 實例。支援多個筆記本、影像/圖表輸出、核心管理和錯誤復原迴圈。適用於資料探索、可重現分析,或讓代理像團隊成員一樣操作筆記本。

為什麼要用

核心特性

即時演示

實際使用效果

jupyter.replay ▶ 就緒
0/0

安裝

選擇你的客戶端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "jupyter": {
      "command": "uvx",
      "args": [
        "jupyter-mcp-server"
      ],
      "_inferred": true
    }
  }
}

開啟 Claude Desktop → Settings → Developer → Edit Config。儲存後重啟應用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "jupyter": {
      "command": "uvx",
      "args": [
        "jupyter-mcp-server"
      ],
      "_inferred": true
    }
  }
}

Cursor 使用與 Claude Desktop 相同的 mcpServers 格式。專案級設定優先於全域。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "jupyter": {
      "command": "uvx",
      "args": [
        "jupyter-mcp-server"
      ],
      "_inferred": true
    }
  }
}

點擊 Cline 側欄中的 MCP Servers 圖示,然後選 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "jupyter": {
      "command": "uvx",
      "args": [
        "jupyter-mcp-server"
      ],
      "_inferred": true
    }
  }
}

格式與 Claude Desktop 相同。重啟 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "jupyter",
      "command": "uvx",
      "args": [
        "jupyter-mcp-server"
      ]
    }
  ]
}

Continue 使用伺服器物件陣列,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "jupyter": {
      "command": {
        "path": "uvx",
        "args": [
          "jupyter-mcp-server"
        ]
      }
    }
  }
}

加入 context_servers。Zed 儲存後熱重載。

claude mcp add jupyter -- uvx jupyter-mcp-server

一行命令搞定。用 claude mcp list 驗證,claude mcp remove 移除。

使用場景

實戰用法: jupyter-mcp-server

如何使用 Claude + Jupyter 進行探索式資料分析

👤 資料科學家、分析師 ⏱ ~30 min intermediate

何時使用: 你有一個新的資料集,想要探索它而不需要自己寫樣板儲存格。

前置條件
  • 執行帶有令牌認證的 JupyterLab — jupyter lab --no-browser;從 URL 複製令牌
  • JUPYTER_URL + JUPYTER_TOKEN 環境變數 — 設定為你的 lab URL 和令牌
步驟
  1. 載入筆記本和資料
    使用 use_notebook 開啟 analysis.ipynb。插入一個儲存格,將 ./data/events.parquet 載入到名為 df 的 DataFrame。✓ 已複製
    → 儲存格執行;df.head() 預覽已返回
  2. 迭代分析
    event_type 的分佈看起來如何?繪製它,給我看影像。✓ 已複製
    → 直方圖影像在聊天中呈現
  3. 儲存乾淨的筆記本
    清理筆記本:刪除錯誤儲存格、新增 markdown 標題、重新啟動並執行全部以驗證它從上到下執行。✓ 已複製
    → 從頭到尾重現的筆記本

結果: 具有敘述、圖表和驗證可重現性的可發布筆記本。

注意事項
  • 核心狀態與筆記本儲存格順序不同步 — 在編輯後使用 notebook_run-all-cells 來捕捉隱藏狀態錯誤
  • 資料檔案對核心不可見 — 核心的 CWD 是筆記本的目錄,不是你啟動 Jupyter 的地方 — 使用絕對路徑
搭配使用: filesystem

使用 Claude 和 jupyter-mcp 的自療癒筆記本

👤 迭代管道的研究人員 ⏱ ~45 min advanced

何時使用: 長筆記本在中途失敗;你希望代理修復儲存格並繼續,而不是重新啟動。

步驟
  1. 執行並捕捉錯誤
    執行 pipeline.ipynb 中的所有儲存格。當儲存格出錯時,讀取回溯、修復代碼,並在繼續前重試。✓ 已複製
    → 筆記本應用修復後超過第一個錯誤繼續
  2. 記錄修復以供審查
    將你做的每個修復總結為已變更代碼上方的 markdown 儲存格✓ 已複製
    → 代理編輯的審計日誌

結果: 管道完成,具有可見的修復歷史。

從自然語言課程大綱生成教學筆記本

👤 教育工作者、技術寫手 ⏱ ~30 min beginner

何時使用: 你想為學生或部落格文章製作一個實際操作筆記本。

步驟
  1. 大綱 → 架構
    從這個課程大綱 [貼上],建立 lesson.ipynb,其中章節為 markdown 儲存格,代碼儲存格已架構。✓ 已複製
    → 具有結構的筆記本
  2. 填充代碼儲存格並驗證
    用可執行範例充實每個代碼儲存格。從上到下執行並確保零錯誤。✓ 已複製
    → 學生可以執行的乾淨筆記本

結果: 在幾分鐘內而不是幾小時內建立的教學就緒筆記本。

組合

與其他 MCP 搭配,撬動十倍槓桿

jupyter + filesystem

將工件移入/移出筆記本的工作目錄

透過 filesystem MCP 將筆記本保存的圖表複製到 ./reports/<date>/。✓ 已複製
jupyter + postgres

從筆記本內的 Postgres 拉取資料

在新儲存格中,使用 pandas.read_sql 和我的 DB 連接載入上個月的事件;然後進行 EDA。✓ 已複製

工具

此 MCP 暴露的能力

工具輸入參數何時呼叫成本
use_notebook path: str 開啟/附加筆記本 0
list_notebooks 尋找可用的筆記本 0
execute_cell notebook_id, cell_index 執行特定儲存格 核心時間
insert_execute_code_cell notebook_id, code, position? 新增代碼並執行它 核心時間
read_cell notebook_id, cell_index 檢查現有儲存格 0
list_kernels 查看正在執行的內容;尋找殭屍核心 0
restart_notebook notebook_id 乾淨地重設核心狀態 0

成本與限制

運行它的成本

API 配額
MCP 沒有;Jupyter 由你執行
每次呼叫 Token 數
輸出可能很大 — 尤其是影像和 DataFrame 標題
費用
免費(自託管)
提示
使用 df.head()df.info(),不要 print(df) — 完整 DataFrames 會使 token 使用量增加

安全

權限、密鑰、影響範圍

憑證儲存: JUPYTER_TOKEN 在環境中 — 像密碼一樣對待;任何擁有它的人都可以在你的核心上執行代碼
資料出站: MCP 僅與你的 Jupyter 伺服器 URL 通信

故障排查

常見錯誤與修復

連接到 Jupyter 時 401 未授權

JUPYTER_TOKEN 過期 — 從 jupyter server list 複製新的

驗證: curl -H 'Authorization: token <TOKEN>' $JUPYTER_URL/api
核心忙碌 / 從不返回

前一個儲存格仍在執行。使用 restart_notebook 復原;注意無限迴圈

驗證: list_kernels 顯示 state=busy
圖表不會出現在 Claude 中

確保設定 %matplotlib inline 並且你正在返回圖形,而不只是在末尾呼叫 plt.show()

替代方案

jupyter-mcp-server 對比其他方案

替代方案何時用它替代權衡
nteract/papermill你想要指令碼/參數化筆記本執行,不需要互動式聊天沒有代理迴圈;批次風格
marimo你想要反應式筆記本,隱藏狀態較少完全不同的工具;還沒有 MCP

更多

資源

📖 閱讀 GitHub 上的官方 README

🐙 查看未解決的 issue

🔍 瀏覽全部 400+ MCP 伺服器和 Skills