AI导哈

Jupyter笔记本服务器

一个用于加载、编辑、搜索和保存Jupyter笔记本的FastMCP服务器，支持实时单元格索引更新和Markdown格式导入导出。

  • by g0g5
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 g0g5/jupyter-notebook-mcp

使用说明

jupyter笔记本电脑mcp

用于加载、编辑、搜索和保存Jupyter笔记本的FastMCP服务器(.ipynb)通过MCP工具。

服务器一次保持一个笔记本打开，并使用实时单元格索引，这些索引会随着单元格的插入或删除而更新。

特性

  • 具有内存中状态的单个活动笔记本会话(path，笔记本对象，脏标志）
  • 加载其他笔记本之前自动保存当前笔记本
  • 真正的插入/删除语义：索引在编辑后立即移动
  • 加载时以纯文本块形式返回完整笔记本
  • 以markdown块格式保存/导入笔记本内容
  • 使用上下文片段进行不区分大小写的关键字搜索
  • 可操作的 ToolError 常见故障案例的消息

工具API

服务器公开了以下MCP工具：

  • load_notebook(path: str)
    • 加载并验证笔记本
    • 首先自动保存当前打开的笔记本（如果有的话）
    • 以纯文本块形式返回活动单元格： [index:N type:...] +完整内容
  • save_notebook(path: str | None = None)
    • 保存当前笔记本（可选地保存到新路径）
  • read_cell(index: int)
    • 返回一个活动单元格的完整源代码
  • add_cell(content: str, cell_type: str = "code", index: int | None = None)
    • 在以下情况下附加新单元格 index 省略
    • 在引用的单元格下方插入 index 提供（插入 index + 1)
    • 返回已更改单元格+相邻单元格的纯文本块
  • replace_cell(index: int, content: str)
    • 替换整个细胞源
  • remove_cell(index: int)
    • 按索引删除单元格，并立即重新索引
    • 返回已更改单元格+相邻单元格的纯文本块
  • delete_cell(index: int)
    • 向后兼容的别名 remove_cell
  • save_markdown(path: str)
    • 保存由返回的相同文本 load_notebook() 到markdown文件路径
  • from_markdown(path: str)
    • 从磁盘读取导出的标记块并替换当前的笔记本单元格
  • search_cell(keywords: str)
    • 空格分隔的关键字搜索（所有关键字必须匹配）

需求

  • python >=3.12
  • uv 用于环境和依赖关系管理

MCP安装

直接与 uvx （无持久安装）：

uvx jupyter-notebook-mcp --from git+https://github.com/g0g5/jupyter-notebook-mcp

安装为 uv 工具：

uv tool install jupyter-notebook-mcp --from git+https://github.com/g0g5/jupyter-notebook-mcp

快速开始

uv sync
uv run python -m jupyter_notebook_mcp

您还可以通过项目脚本入口点运行：

uv run jupyter-notebook-mcp

MCP客户端配置（stdio）

使用以下配置之一。

选项1：运行 uvx 来自GitHub：

{
  "mcpServers": {
    "jupyter-notebook-mcp": {
      "command": "uvx",
      "args": [
        "jupyter-notebook-mcp",
        "--from",
        "git+https://github.com/g0g5/jupyter-notebook-mcp"
      ]
    }
  }
}

选项2：之后 uv tool install，直接运行installed命令：

{
  "mcpServers": {
    "jupyter-notebook-mcp": {
      "command": "jupyter-notebook-mcp",
      "args": []
    }
  }
}

发展

安装/更新依赖关系：

uv sync

类型检查（轻量级编译检查）：

uv run python -m py_compile jupyter_notebook_mcp/*.py tests/*.py

运行测试：

uv run pytest -v

项目结构

jupyter-notebook-mcp/
|- jupyter_notebook_mcp/
|  |- __main__.py                  # Module entrypoint for `python -m jupyter_notebook_mcp`
|  |- server.py                    # FastMCP app and tool registration
|  |- session.py                   # Shared in-memory notebook session state
|  |- notebook_io.py               # Notebook load/save and validation
|  |- cell_ops.py                  # Cell read/edit operations
|  |- markdown_codec.py            # Markdown export/import parsing
|  |- search.py                    # Keyword search and snippet extraction
|  \- formatting.py                # Cell block and markdown preview formatting
\- tests/
   |- conftest.py                  # Shared fixtures (session reset)
   |- helpers.py                   # Shared notebook test helpers
   |- test_contract_flow.py
   |- test_session_and_io.py
   |- test_cell_editing.py
   |- test_markdown_codec.py
   \- test_search_and_formatting.py

行为说明

  • 如果未加载笔记本，则依赖笔记本的工具将返回：
    • No notebook is loaded. Use load_notebook(path) first.
  • 细胞指数始终是当前活跃指数；插入/删除操作会重新索引以下单元格。
  • 保存时，服务器通过以下方式验证笔记本结构 nbformat.validate 在写作之前。

相关 MCP