Skip to main content
Glama
jupyter-vscode-mcp

jupyter-vscode-mcp

by hadiproz

Jupyter VS Code MCP

License: MIT MCP

VS Code 扩展,将 Jupyter notebook 操作以基于纯 HTTP 的 MCP 工具形式暴露出来——一个适用于所有 AI 编码代理的可移植 URL。无需绝对路径,无需 node 命令,无需 stdio 接线。

将任何 MCP 客户端指向该 URL,代理即可在您的实时编辑器会话中探索、编辑、运行和调试 notebook:它看到的单元格与您看到的一致,与您的 notebook 所使用的内核通信(本地或远程——包括 Colab),并且每个操作都会落到真实的 VS Code UI 中。

功能

具有稳定单元格句柄的 Notebook 编辑

  • 每个单元格通过统一的方案标识:#NB-xxxxxxxx,持久化存储在标准 nbformat 4.5 的 cell id 字段中。它不受编辑、其他单元格的插入/删除、索引移位、保存/重新打开、扩展重载的影响——甚至将文件复制到另一台机器也依然有效。

  • 删除后 ID 永远不会被回收:新单元格始终获得全新的随机 ID。jupyter_get_summary 会为任何缺少 ID 的单元格(例如在 UI 中手动创建的单元格)分配 ID,因此每个报告的句柄都可以立即复用。

  • 索引处处从 0 开始(摘要、源码、运行范围、输出)——没有混合约定。

非阻塞执行控制

  • jupyter_run_cells 启动执行并立即返回;使用 jupyter_wait_until_idle 轮询,或使用 jupyter_get_status 获取快照。没有盲目睡眠,长单元格不会触发 MCP 超时。

  • 内核就绪保护:针对已死/缺失的内核运行时,返回可操作的提示而不是卡住。

  • jupyter_interrupt_kernel 中止当前运行,同时保留所有变量。

内核智能(Copilot 级)

  • jupyter_get_variables —— 类型感知的变量报告:DataFrame/Series 以 {shape, columns[:8], head(2)} 形式呈现,ndarray 以 {shape, dtype} 形式呈现,容器包含 length,标量以简短 repr 呈现。在可用时使用官方 Jupyter 变量视图 API,否则使用静默内核探测,绝不触碰执行计数。可选的文档符号过滤仅在符号实际可用时才隐藏内部噪音。

  • jupyter_get_pip_packages —— 来自活动内核环境的包清单(名称 + 版本)。

  • jupyter_install_packages —— pip 在内核自身的解释器内部运行,因此包会安装到 notebook 实际使用的运行时中——包括 Colab 等远程虚拟机,绝不安装到本地主机。支持版本规格和 --upgrade,之后验证每个规格是否解析成功,并如实报告失败(附上 pip 的真实输出尾部),而不是假装成功。

  • jupyter_get_status 探测实时内核以获取真实的 Python 版本/平台,而不是信任过时的元数据。

  • jupyter_select_kernel 在没有活动内核时打开 VS Code 的原生内核选择器。

纯网络 MCP 传输

  • 可流式 HTTP(MCP 规范 2025-11-25),响应为纯 JSON——一个最小客户端仅凭 curl 即可工作。

  • 端点:/mcp(另有旧版 /sse),GET /health 用于存活检查 + 版本探测。

  • 支持多个并发代理会话;会话在端口热变更后仍然有效。

如实报告

错误携带上下文和下一步提示:内核缺失 → 启动引导,ID 过期 → 通过摘要刷新,pip 安装失败 → 真实的 pip 错误尾部,内核繁忙 → 明确的延迟说明,而不是静默地返回空结果。

Related MCP server: Jupyter MCP Server

工具

工具

描述

jupyter_list_open_notebooks

打开的 notebook,包含 URI、路径、单元格数量、脏标记

jupyter_get_summary

紧凑映射:稳定 ID、类型、执行状态、输出 MIME 类型、预览

jupyter_get_cell_source

按 ID 或 0 基索引获取单个单元格的源码;支持按行分页

jupyter_edit_cell

替换源码;之后 ID 仍然有效

jupyter_insert_cell / jupyter_delete_cell

在 0 基位置进行结构编辑;全新的不可回收 ID

jupyter_save_notebook

将 .ipynb 持久化到磁盘

jupyter_create_notebook

在磁盘上创建空的 .ipynb 并在编辑器中打开

jupyter_run_cells

非阻塞启动:索引范围 [start,end) 或有序 ID 列表

jupyter_wait_until_idle

轮询直到空闲或超时;返回已完成的单元格 + 成功标志

jupyter_get_status

即时快照:kernelStatus、实时运行时信息、运行中的单元格、脏状态

jupyter_interrupt_kernel

中止当前执行,保留变量

jupyter_restart_kernel

完全重启(清除变量)

jupyter_get_outputs

内联输出(短文本)或位于 .jupyter-mcp/artifacts/ 下的产物文件

jupyter_get_variables

类型感知的内核变量报告

jupyter_get_pip_packages

内核环境的已安装包清单

jupyter_install_packages

内核侧 pip 安装,支持版本规格 + 安装后验证

jupyter_select_kernel

打开原生内核选择器,并报告结果状态

稳定的单元格 ID

每个单元格都会获得一个随机持久 ID(#NB-xxxxxxxx),写入标准 nbformat 4.5 的 cell id 字段——该字段正是平台本身在保存/加载时读取并往返使用的同一槽位。该 ID 不受位置变化、内容编辑、兄弟单元格插入/删除以及重新打开循环的影响。优先使用 ID 而非索引;调用 jupyter_get_summary 来发现它们(它还会为在工具之外创建的单元格补填缺失的 ID)。

裸 8 位十六进制输入(abcd1234)可作为 #NB-abcd1234 的简写形式。

兼容的代理

任何支持 HTTP 的 MCP 客户端均可用。常见配置:

Claude Code、Cursor、Windsurf、Cline、Copilot:

{
  "mcpServers": {
    "jupyter-vscode-mcp": {
      "url": "http://localhost:9123/mcp"
    }
  }
}

OpenCode、Kilo Code:

{
  "mcp": {
    "jupyter-vscode-mcp": {
      "type": "remote",
      "url": "http://localhost:9123/mcp",
      "enabled": true
    }
  }
}

从命令面板运行 “Jupyter VS Code MCP: Show MCP Configuration” → 选择您的代理 → 代码片段即复制到剪贴板。

安装与运行

从 Releases 下载最新的 .vsix,然后:

code --install-extension jupyter-vscode-mcp-<version>.vsix
  1. 打开任意 .ipynb —— 服务器自动在 127.0.0.1:9123 上启动(状态栏显示状态;点击可切换)。

  2. 将上面的 URL 配置添加到您的代理中。

  3. 随时探测存活状态:curl http://localhost:9123/health。

设置:jupyter-vscode-mcp.mcpPort(默认 9123,热应用),jupyter-vscode-mcp.autoStart(默认 true)。

推荐工作流

jupyter_list_open_notebooks   → pick notebook
jupyter_get_summary           → stable #NB-* IDs, exec state        (0-based)
jupyter_get_cell_source       → read only what you need
jupyter_edit_cell             → IDs stay valid after edits
jupyter_run_cells             → starts async, returns immediately
jupyter_wait_until_idle       → blocks until done (or poll get_status)
jupyter_get_outputs           → inline short text, artifact files for big/binary
jupyter_get_variables         → inspect kernel state after runs

架构

AI agent ──HTTP/JSON-RPC──▶ VS Code extension (in-process http server :9123)
                                 │ vscode.* APIs + ms-toolsai.jupyter public API
                                 ▼
                     notebook cells, outputs, kernel status

内核交互使用有文档记载的 ms-toolsai.jupyter 公共 API(kernel.executeCode、中断/重启命令、变量/pip 列举命令),并带有命令回退;执行跟踪依赖于 workspace.onDidChangeNotebookDocument。

开发

npm install
npm run compile      # typecheck
npm run lint
npm run build        # esbuild bundle
npm run smoke        # local protocol smoke test (vscode stubbed)
npx @vscode/vsce package

参考

许可证

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables AI agents to interact with Jupyter notebooks via MCP tools for querying, modifying, executing, and setting up notebooks, with state preservation and real-time collaboration.
      4
      46
      Apache 2.0
    • A
      license
      B
      quality
      D
      maintenance
      An MCP server that connects directly to a Jupyter kernel via ZMQ, enabling AI assistants to read, create, edit, execute, and manage Jupyter Notebooks as MCP tools.
      9
      MIT