mcp-server-jupyter 使用说明

项目简介

mcp-server-jupyter 是一个基于 Model Context Protocol (MCP) 构建的服务器，旨在使大型语言模型（LLM）能够与 Jupyter Notebook 进行交互。通过提供一系列工具，该服务器允许 LLM 客户端读取笔记本内容、修改单元格、执行代码并获取输出，从而实现 Jupyter Notebook 的自动化管理和操作。

主要功能点

读取 Notebook 内容: 提供多种工具读取 Notebook 的内容，包括带输出和不带输出的完整读取，以及读取特定单元格的输出。
编辑 Notebook 单元格: 允许 LLM 客户端向 Notebook 添加新的单元格（代码或 Markdown），以及编辑现有单元格的内容。
执行 Notebook 单元格: 支持执行指定的 Notebook 单元格，并返回执行结果，方便 LLM 验证代码执行和获取数据。
基于 MCP 协议: 遵循 MCP 协议标准，易于与支持 MCP 协议的 LLM 客户端集成，如 Claude Desktop。
支持 Stdio 和 SSE 传输: 服务器支持标准的 Stdio 以及 SSE (Server-Sent Events) 传输协议，可以根据需要选择合适的通信方式。

安装步骤

安装 uv: 强烈推荐使用 'uv' 包管理器，它可以更方便地管理 Python 环境和包依赖。如果尚未安装，请先安装 'uv'：
```
pip install uv
```

创建虚拟环境: 使用 'uv' 创建一个新的虚拟环境，并进入该环境：

uv venv --seed
source .venv/bin/activate

安装 JupyterLab: 'mcp-server-jupyter' 需要 JupyterLab 或 Jupyter Notebook 环境来操作 Notebook 文件，使用 'uv' 安装 'jupyterlab'：
```
uv pip install jupyterlab
```

安装 mcp-server-jupyter: 使用 'uv' 安装 'mcp-server-jupyter' 包：

uv pip install mcp-server-jupyter

服务器配置

以下是配置 MCP 客户端（例如 Claude Desktop）以连接到 'mcp-server-jupyter' 服务器的 JSON 格式配置信息。您需要将此配置添加到 MCP 客户端的配置文件中。

{
  "mcpServers": {
    "Jupyter-notebook-manager": { // 服务器名称，可以自定义
      "command": "uv", // 启动服务器的命令，这里使用 uv
      "args": ["run", "--with", "mcp-server-jupyter", "mcp-server-jupyter"], // 启动参数，指定使用 uv 运行 mcp-server-jupyter
      "env": {
        "UV_PROJECT_ENVIRONMENT": "/path/to/venv_for_jupyter/.venv" // 虚拟环境路径，请替换为您的虚拟环境的实际路径，例如 "/Users/username/my_project/.venv"
      }
    }
  }
}

注意:

'UV_PROJECT_ENVIRONMENT' 环境变量需要设置为您安装 'jupyterlab' 和 'mcp-server-jupyter' 的虚拟环境路径。您可以通过在虚拟环境目录下执行 'echo $(pwd)/.venv' 获取该路径。
请确保 JupyterLab 或 Jupyter Notebook 实例已启动并在运行，'mcp-server-jupyter' 服务器才能正常工作。

基本使用方法

启动 JupyterLab 或 Jupyter Notebook: 在您的虚拟环境中启动 JupyterLab 或 Jupyter Notebook：

.venv/bin/jupyter lab

或

.venv/bin/jupyter notebook

配置 MCP 客户端: 将上面提供的服务器配置 JSON 添加到您的 MCP 客户端配置文件中（例如 Claude Desktop 的 'claude_desktop_config.json'）。
打开 Notebook: 在 JupyterLab 或 Jupyter Notebook 中打开您想要操作的 Notebook 文件。
获取 Notebook 路径: 获取您要操作的 Notebook 文件的完整系统路径。在 JupyterLab 中，右键单击 Notebook 文件，选择 "Copy Path"；在 Jupyter Notebook 中，从浏览器地址栏复制路径并修改为完整系统路径。
在 MCP 客户端中使用工具: 在 MCP 客户端中，您可以使用 'mcp-server-jupyter' 提供的工具（例如 'read_notebook_with_outputs', 'add_cell', 'execute_cell' 等）与 Jupyter Notebook 进行交互。在调用工具时，请务必使用 Notebook 的完整路径作为参数。
刷新 Notebook: 通过 MCP 客户端对 Notebook 进行修改（例如添加、编辑单元格）后，您需要在 JupyterLab 或 Jupyter Notebook 中手动刷新页面以查看更改。当前版本不支持自动刷新。

请确保在与 MCP 客户端交互期间，JupyterLab 或 Jupyter Notebook 实例保持运行状态。

关键词