AI导哈

Jupyter笔记本协议服务器

一个专注于安全读取、编辑和执行实时Jupyter笔记本的模型上下文协议服务器。

  • by kshitijdesai99
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 kshitijdesai99/jupyter_mcp_server_kshitij

使用说明

Jupyter MCP服务器

A专注 模型上下文协议 用于安全读取的服务器， 用于创建、编辑和执行一个实时Jupyter笔记本。

实现故意保持小规模：一个笔记本电脑、一个内核和标准 stdio 运输。操作共享会话锁，代码被追加并执行一次 服务器等待内核的最终执行回复，而不是第一个可见的输出。

它暴露了什么

MCP图元 名称 用途
工具 add_markdown_cell 添加并验证一个标记单元格
工具 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 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检查员。

安全和生命周期保证

  • 导入模块不执行网络I/O。
  • MCP生命周期清理在正常或异常关机时关闭笔记本电脑和内核客户端。
  • 一 asyncio.Lock 防止并发笔记本突变、执行、读取和重新启动。
  • 使用笔记本客户端的公共序列/导出API；私有的 _doc 和 _ycells 内部结构 无法访问。
  • 内核错误和超时成为MCP错误。一个超时的内核被中断，一个不确定的 会话在重用之前被丢弃。
  • 标准 stdio 运输已启用；不存在静默的原始TCP回退。

相关 MCP