Vscode Runtime Notebook MCP

Jupyter笔记本MCP服务器

Jupyter Notebook MCP Server

一个VS代码/光标扩展，通过MCP（模型上下文协议）公开Jupyter笔记本操作：读取/编辑/运行单元格并捕获输出。可与Claude Code、Cursor Agent、Windsurf和任何兼容MCP的AI助手配合使用。

安装： VS代码市场 · 打开VSX ·

\[！重要\] 该项目仍处于alpha之前 所以它的边缘很粗糙。在多个窗口中工作是不稳定的。

为什么要连接VS代码运行时API？

目前有两种主要的架构可以让AI代理访问Jupyter笔记本。这个项目受到了这两个方面的极大启发——感谢这些团队开创了这一领域：

架构1：基于文件（例如。， 光标笔记本mcp)

这些服务器读/写 .ipynb 直接使用库的文件，如 nbformat.

赞成的意见： 无服务器依赖关系，开箱即用

欺骗：

• 无法执行代码 -代理只能编辑单元格，用户必须手动运行它们
• UI同步问题-在您还原/重新打开之前，VS代码可能会显示过时的内容
• 这 .ipynb JSON格式很冗长（比原始代码多约3倍的标记）
• 代理写入时编辑的比赛条件

体系结构2:Jupyter服务器API（例如。， jupyter mcp服务器)

这些服务器连接到Jupyter的REST API，可以通过内核执行代码。

赞成的意见： 可以执行代码， 独立远程JupyterLab/JupyterHub部署的最佳选择

欺骗：

• 需要单独运行JupyterLab(jupyter lab --port 8888)
• 身份验证设置：令牌、URL、环境变量
• 你最终会运行两个UI：一个用于笔记本电脑，另一个用于人工智能
• 如果你在VS Code中打开笔记本，你就创建了另一个真实来源（Jupyter服务器状态与你的编辑器）

架构3:VS代码/游标运行时API（此扩展）

我们引入了第三种体系结构-直接挂接到Cursor/VS Code的Notebook API中，这与编辑器内部使用的API相同。

赞成的意见：

• 零配置-只需安装，服务器自动启动
• 阅读速度更快 （直接内存访问，无序列化）
• 执行现有内核中的代码（VS code已经管理的内核）
• 更改会立即出现在编辑器中，并提供完全的撤消/重做支持
• 单一真相来源：你所看到的就是代理人所看到的
• 适用于远程内核——如果VS Code连接到远程Jupyter服务器，代理也会连接

欺骗：

• 仅在VS Code/Coursor内部工作（如果您使用JupyterLab web UI，则无济于事）

何时使用什么

特性

• 执行代码 在活动内核中检索输出
• 全细胞操作 -插入、编辑、删除、移动单元格
• 读取单元格内容和输出 包括图像（base64）
• 搜索和导航 -查找文本，获取笔记本大纲
• 批量操作 -添加多个单元格，清除所有输出

工具（15）

导航与阅读

细胞操作

执行和输出

要执行即席代码，请使用 notebook_insert_cell 随着 execute: true。要执行现有单元格，请使用 notebook_run_cell.

Tool Parameters

所有工具支持 response_format 参数("markdown" 或 "json").

notebook_insert_cell

{
  "content": "print('hello')",
  "type": "code",
  "index": 0,
  "language": "python",
  "execute": false
}

notebook_edit_cell

{
  "index": 0,
  "content": "# New content"
}

笔记本搜索

{
  "query": "import pandas",
  "case_sensitive": false,
  "context_lines": 1
}

笔记本_move_cell

{
  "from_index": 5,
  "to_index": 0
}

notebook_bulk_add_cells

{
  "cells": [
    {"content": "# Header", "type": "markdown"},
    {"content": "x = 1", "type": "code", "language": "python"}
  ],
  "index": 0
}

notebook_run_cell

{
  "index": 0
}

设置

1. 在VS Code或Cursor中安装扩展
2. 添加到MCP客户端配置中：

{
  "mcpServers": {
    "notebook": {
      "url": "http://127.0.0.1:49777/mcp"
    }
  }
}

\[！注意\] 当VS代码/光标打开时，服务器会自动启动。寻找 🪐 :49777 状态栏中的指示器。

配置

演出

使用471单元笔记本电脑进行测试（约2.8MB，1MB输出）：

读取操作是亚毫秒级的，因为它们直接访问内存中的数据结构。写操作（~7ms）通过VS Code的编辑管道进行撤消/重做支持。

需求

• VS代码1.85+或光标0.43+
• Jupyter扩展

建筑

┌─────────────────────────────────────────────────────────────────────────┐
│                         VS Code / Cursor                                │
│                                                                         │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │                    Jupyter Extension                              │  │
│  │                                                                   │  │
│  │   Notebook Document  ◄───►  Kernel (Python)  ───►  Outputs        │  │
│  │                                    ▲                              │  │
│  └────────────────────────────────────┼──────────────────────────────┘  │
│                                       │                                 │
│  ┌────────────────────────────────────┼──────────────────────────────┐  │
│  │              Notebook MCP Server Extension                        │  │
│  │                                    │                              │  │
│  │   ┌────────────────────────────────┴───────────────────────────┐  │  │
│  │   │                  HTTP Server (:49777)                      │  │  │
│  │   │                                                            │  │  │
│  │   │  execute_code  insert_cell  list_cells  get_output  ...    │  │  │
│  │   └────────────────────────────────────────────────────────────┘  │  │
│  └───────────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    │ HTTP (MCP Protocol)
                                    ▼
                    ┌───────────────────────────────┐
                    │           AI Agent            │
                    │   (Claude Code, Cursor, etc)  │
                    └───────────────────────────────┘

运作原理

1. 扩展嵌入了一个基于HTTP的MCP服务器（端口49777）
2. AI代理（Claude Code、Cursor agent等）通过MCP协议发送工具调用
3. 服务器使用VS代码/光标API来操纵活动笔记本
4. 更改会立即显示在编辑器中
5. 输出被捕获并返回给代理

这使得在VS Code和Cursor中与AI代理进行真正的交互式笔记本会话成为可能。