Jupyter VS Code 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

工具

稳定的单元格 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

参考

• Model Context Protocol —— 可流式 HTTP 传输，规范 2025-11-25

• microsoft/vscode-copilot-chat (MIT) —— 变量摘要、截断预算和符号过滤模式

• SMARK OpenCode IDE Bridge —— 通过 Jupyter 公共 API 进行内核预检查、中断/重启命令回退、基于事件的完成跟踪

• kriss-spy/opencode-jupyter —— 原始 HTTP 桥接概念

许可证

MIT