mcp-server-jupyter

mcp-server-jupyter

用于以编程方式管理和操作 Jupyter 笔记本的 MCP 服务。

组件

工具

该服务提供六种用于操作笔记本的工具：

1. read_notebook_with_outputs：读取笔记本内容，包括单元格输出

   • 必填：notebook_path（字符串）

2. read_notebook_source_only：读取笔记本内容，不包括输出

   • 必填：notebook_path（字符串）
   • 当大小限制导致无法读取包含输出的完整笔记本时使用

3. read_output_of_cell：读取特定单元格的输出

   • 必填：
     • notebook_path（字符串）
     • cell_id（字符串）

4. add_cell：向笔记本添加新单元格

   • 必填：
     • notebook_path（字符串）
     • source（字符串）
   • 可选：
     • cell_type（字符串）：“code”或“markdown”
     • position（整数）：插入索引（-1 表示追加）

5. edit_cell：修改现有单元格内容

   • 必填：
     • notebook_path（字符串）
     • cell_id（字符串）：要编辑的单元格的唯一 ID
     • source（字符串）

6. execute_cell：执行特定单元格并返回其输出

   • 必填：
     • notebook_path（字符串）
     • cell_id（字符串）
   • 可用于验证单元格是否已执行以及输出内容

搭配 Claude Desktop 使用

步骤 1：启动 JupyterLab 或 Jupyter Notebook

使用 uv 运行 Jupyter 笔记本，可以更轻松地管理虚拟环境和软件包安装。

更多详情请参阅 uv jupyter 文档。

uv venv --seed
source .venv/bin/activate
uv pip install jupyterlab
.venv/bin/jupyter lab

注意：此环境应作为 MCP 服务中的 UV_PROJECT_ENVIRONMENT 环境变量（下一步）。请在启动 Jupyter 的同一文件夹中运行。

echo $(pwd)/.venv

步骤 2：配置 Claude Desktop 将此配置添加到 Claude Desktop 配置文件中：

PyPi 软件包：

// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "Jupyter-notebook-manager": {
      "command": "uv",
      "args": ["run", "--with", "mcp-server-jupyter", "mcp-server-jupyter"],
      "env": {
        "UV_PROJECT_ENVIRONMENT": "/path/to/venv_for_jupyter/.venv"
      }
    }
  }
}

Git 仓库分支

// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "Jupyter-notebook-manager": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/Users/inna/mcp-server-jupyter/src/mcp_server_jupyter",
        "mcp-server-jupyter"
      ],
      "env": {
        "UV_PROJECT_ENVIRONMENT": "/path/to/venv_for_jupyter/.venv"
      }
    }
  }
}

步骤 3：打开笔记本和 Claude 聊天

在 JupyterLab/Jupyter Notebook 中打开或创建笔记本

获取笔记本的完整路径：

• 在 JupyterLab 中：在文件浏览器中右键单击笔记本 →“复制路径”
• 在 Jupyter Notebook 中：从 URL 复制路径（修改为完整系统路径）

在 Claude Desktop 聊天中：

• 调用工具时始终使用笔记本的完整路径
• 示例：/Users/username/projects/my_notebook.ipynb

重要说明：

• 通过 Claude 进行任何修改（add_cell、edit_cell）后：
  • 在 JupyterLab/Jupyter Notebook 中重新加载笔记本页面
  • 当前版本不支持自动重新加载
• 使用 Claude 时，请保持 JupyterLab/Jupyter Notebook 实例运行

许可证

本项目采用 MIT 许可证授权。详情请参阅 LICENSE 文件。