Robust new jupyter server

Jupyter MCP 服务

一个专注于安全读取、编辑和执行单个实时 Jupyter 笔记本的 Model Context Protocol 服务。

此实现刻意保持精简：一个笔记本、一个内核，以及标准 stdio 传输。各项操作共用一个会话锁，代码只会追加和执行一次，服务会等待内核返回最终执行结果，而不是第一个可见输出。

提供的功能

MCP 基元	名称	用途
工具	add_markdown_cell	追加并验证一个 Markdown 单元格
工具	add_execute_code_cell	追加一次、执行一次，并返回结构化输出
工具	read_notebook_content	读取一致的笔记本快照
工具	kernel_restart	干净地替换当前内核／会话
资源	jupyter://notebook	只读笔记本 JSON
提示词	analyse_notebook	在更改笔记本前进行分析

HTML、图像、JSON、流、结果和回溯数据都会保留在结构化输出模型中。执行失败、超时和结果未知都会作为 MCP 错误返回，而不是伪装成成功字符串。

要求

• Python 3.10 或更高版本（推荐 3.12）
• 启用了实时协作功能的 JupyterLab 服务
• uv（推荐）或 pip

本地设置

安装服务和开发工具：

uv sync --extra dev

创建有效的笔记本文档（空文件并不是笔记本）：

uv run python -c "import nbformat; nbformat.write(nbformat.v4.new_notebook(), 'notebook.ipynb')"

在另一个环境或终端中安装并启动 Jupyter：

uv run --with jupyterlab --with jupyter-collaboration \
  jupyter lab \
  --port 8888 \
  --ServerApp.port_retries 0 \
  --ServerApp.root_dir . \
  --IdentityProvider.token MY_TOKEN \
  --no-browser

运行 MCP 服务：

NOTEBOOK_PATH=notebook.ipynb \
SERVER_URL=http://localhost:8888 \
TOKEN=MY_TOKEN \
uv run jupyter-mcp

服务会在首次使用时连接 Jupyter，因此导入软件包或列出 MCP 工具不要求 Jupyter 正在运行。

MCP 客户端配置

对于启动本地 stdio 服务的客户端，请使用以下格式，并将仓库路径替换为你的检出路径：

{
  "mcpServers": {
    "jupyter": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/jupyter_mcp_server_kshitij",
        "run",
        "jupyter-mcp"
      ],
      "env": {
        "NOTEBOOK_PATH": "notebook.ipynb",
        "SERVER_URL": "http://localhost:8888",
        "TOKEN": "MY_TOKEN"
      }
    }
  }
}

配置

变量	默认值	说明
NOTEBOOK_PATH	notebook.ipynb	相对于 Jupyter 服务根目录的路径
SERVER_URL	http://localhost:8888	Jupyter 服务 URL
TOKEN	空	Jupyter 身份验证令牌；请在运行时设置
CONNECTION_TIMEOUT_SECONDS	15	启动、清理和中断的超时时间
EXECUTION_TIMEOUT_SECONDS	30	内核执行的最长时间
CONNECTION_ATTEMPTS	2	修改前的连接尝试次数

连接重试只会发生在修改操作之前。执行一旦开始，断开连接就会产生明确的“结果未知”错误，并且不会自动重复执行单元格。

Docker

构建并运行非 root 镜像。镜像没有默认令牌，必须在运行时提供：

docker build -f dockerfile -t jupyter-mcp .
docker run --rm -i \
  -e NOTEBOOK_PATH=notebook.ipynb \
  -e SERVER_URL=http://host.docker.internal:8888 \
  -e TOKEN=MY_TOKEN \
  jupyter-mcp

开发

uv run pytest
uv run ruff check .

单元测试使用模拟的笔记本和内核客户端；不需要运行中的 Jupyter 服务。要进行端到端检查，请按上文所示启动 Jupyter，并使用 MCP 客户端或 MCP Inspector 测试这些工具。

安全与生命周期保证

• 导入模块不会执行网络 I/O。
• MCP 生命周期清理会在正常或异常关闭时关闭笔记本和内核客户端。
• asyncio.Lock 可防止并发修改笔记本、执行、读取和重启。
• 使用笔记本客户端公开的序列／导出 API；不会访问私有的 _doc 和 _ycells 内部属性。
• 内核错误和超时会作为 MCP 错误返回。内核超时后会被中断，状态不确定的会话会在再次使用前丢弃。
• 仅启用标准 stdio 传输；不会静默回退到原始 TCP。