jupyter-mcp服务器扩展版

Name: jupyter-mcp服务器扩展版
Author: itisaevalex

作者：itisaevalex10 星标更新：2025-04-05

安装使用来源：spider==github.com

项目介绍

Jupyter MCP 扩展

通过模型上下文协议增强与 Jupyter 笔记本的交互

该项目提供了一个模型上下文协议 (MCP) 服务器，该服务器能够实现人工智能模型（如 Claude）或其他 MCP 客户端与运行在 JupyterLab 中的实时 Jupyter 笔记本之间的丰富互动。

功能

将 MCP 客户端（例如 Claude Desktop）连接到正在运行的 JupyterLab 实例。
提供一系列用于笔记本互动的工具，包括：
- 单元格管理： 添加、删除、移动、分割、编辑源代码。
- 执行： 执行特定单元格或所有单元格，获取输出。
- 文件系统： 列出目录内容，获取文件内容（含图片缩放）。
- 内核检查： 列出内核变量，列出已安装的包。
- 包管理： 在内核环境中安装包。
- 笔记本状态： 搜索单元格，获取所有单元格信息/输出，设置目标笔记本路径。

要求

Python: 推荐 >= 3.10。强烈建议使用 Conda/Miniconda 这样的专用环境管理器（参见安装步骤）。
JupyterLab: 正在运行的 JupyterLab 实例。
Jupyter 协作扩展： 特定版本 jupyter_collaboration==2.0.1。
datalayer_pycrdt: 必要依赖项。
Docker: 构建和运行 MCP 服务器容器（包括必要的补丁）所必需。
Pillow: 服务器所需（包含在 Docker 构建中），用于处理图像。
一个 MCP 客户端： 如 Claude Desktop。

安装和设置

仔细遵循以下步骤以创建一个基于调试结果的稳定环境：

1. 创建专用 Conda 环境（推荐）：

打开你的终端（Anaconda Prompt 或类似）。如果初始 pip 安装需要管理员权限，请以管理员身份运行终端（尽管使用专用环境通常可以避免这种情况）。

# 创建干净的环境（Python 3.10 在调试期间工作良好）
conda create -n jupyter_mcp_env python=3.10 -y

# 激活环境
conda activate jupyter_mcp_env

记得在运行 pip 或 jupyter lab 命令之前激活此环境（conda activate jupyter_mcp_env）。

2. 安装核心 Jupyter 组件：

# 使用 'python -m pip' 确保正确激活的环境中的 pip
python -m pip install jupyterlab ipykernel

3. 安装特定版本的 jupyter_collaboration：

新版本在调试期间出现问题。需要版本 2.0.1。

# 安装所需的 v2.0.1
python -m pip install "jupyter_collaboration==2.0.1"

4. 处理 pycrdt 依赖项：

按照特定的卸载/重新安装顺序操作：

# 卸载可能冲突的版本
python -m pip uninstall -y pycrdt datalayer_pycrdt

# 安装所需的版本
python -m pip install datalayer_pycrdt

5. 启用协作扩展：

确保扩展在你的环境中启用：

jupyter server extension enable jupyter_collaboration --py --sys-prefix

6. 构建修补的 Docker 镜像：

包含的 Dockerfile 包含了调试期间发现的补丁。本地构建镜像：

# 导航到包含 Dockerfile 的目录
# cd /path/to/your/jupyter-mcp-server/
docker build -t jupyter-mcp-server:latest .

7. 启动 JupyterLab：

确保你的 jupyter_mcp_env conda 环境已激活。

# 使用强且唯一的令牌！
# --ip=0.0.0.0 允许 Docker 容器连接
jupyter lab --port 8888 --IdentityProvider.token YOUR_SECURE_TOKEN --ip 0.0.0.0

安全性： 将 YOUR_SECURE_TOKEN 替换为强且唯一的密码或令牌。不要使用弱令牌。
Windows 终端： 如果使用 Windows 终端/命令提示符，请确保禁用终端窗口的“快速编辑模式”，以防止 Jupyter Lab 的连接挂起（右键点击标题栏 -> 属性 -> 选项 -> 取消选中快速编辑模式）。
防火墙： 确保操作系统防火墙允许 8888 端口的传入连接，特别是来自 Docker 网络接口的连接。

配置

运行在 Docker 中的 MCP 服务器从 MCP 客户端配置（例如 claude_desktop_config.json）传递的环境变量中读取其配置。关键变量：

SERVER_URL: 正在运行的 JupyterLab 的 URL（例如，对于 Docker Desktop Win/Mac 是 http://host.docker.internal:8888，对于 Linux 使用 --network=host 是 http://localhost:8888）。此处不包括令牌。
TOKEN: 与 --IdentityProvider.token 一起使用的精确令牌。
NOTEBOOK_PATH: 相对于 JupyterLab 启动目录的初始目标笔记本路径（例如，notebook.ipynb）。可通过 set_target_notebook 工具更改。
LOG_LEVEL: 服务器日志记录详细程度（DEBUG，INFO，WARNING）。默认值：INFO。
OUTPUT_WAIT_DELAY: 默认等待时间（秒）用于 get_cell_output。默认值：0.5。

使用 Claude Desktop

安装 Claude Desktop。
查找 claude_desktop_config.json。
添加/修改 mcpServers 块，根据你的操作系统和配置进行调整：

Claude 配置（macOS / Windows with Docker Desktop）

{
  "mcpServers": {
    "jupyter": {
      "command": "docker",
      "args": [
        "run",
        "-i", 
        "--rm", 
        "-e", "SERVER_URL", 
        "-e", "TOKEN",
        "-e", "NOTEBOOK_PATH",
        "-e", "LOG_LEVEL=INFO", 
        "jupyter-mcp-server:latest" 
      ],
      "env": {
        "SERVER_URL": "http://host.docker.internal:8888", 
        "TOKEN": "YOUR_SECURE_TOKEN", 
        "NOTEBOOK_PATH": "notebook.ipynb" 
      }
    }
  }
}

Claude 配置（Linux）

{
  "mcpServers": {
    "jupyter": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--network=host", 
        "-e", "SERVER_URL",
        "-e", "TOKEN",
        "-e", "NOTEBOOK_PATH",
        "-e", "LOG_LEVEL=INFO",
        "jupyter-mcp-server:latest"
      ],
      "env": {
        "SERVER_URL": "http://localhost:8888", 
        "TOKEN": "YOUR_SECURE_TOKEN", 
        "NOTEBOOK_PATH": "notebook.ipynb" 
      }
    }
  }
}

保存配置文件并重启 Claude Desktop。

可用工具

此服务器提供了以下工具用于与 Jupyter 互动：

list_notebook_directory() → str
- 列出当前目标笔记本所在位置的文件和目录。目录以 / 结尾。
get_file_content(file_path: str, max_image_dim: int = 1024) → str
- 获取文件内容。文本直接返回。大型图片会按比例缩放（最大尺寸为 max_image_dim）并作为 base64 数据 URI 字符串返回。二进制文件被描述。
set_target_notebook(new_notebook_path: str) → str
- 更改后续工具调用的目标笔记本文件路径（仅限会话）。路径必须是相对路径。
add_cell(content: str, cell_type: str, index: Optional[int] = None) → str
- 在指定索引处添加一个新单元格（'code' 或 'markdown'），如果索引无效或为空则追加。使用稳健的 Yjs 类型创建。
add_code_cell_on_bottom(cell_content: str) → str
- 在笔记本末尾添加一个代码单元格。
execute_cell(cell_index: int) → str
- 发送单元格执行请求（通过 asyncio.to_thread 实现异步发送）。不等待完成。返回确认消息或错误。
execute_all_cells() → str
- 依次发送所有代码单元格的执行请求（异步发送）。返回确认消息或错误。
get_cell_output(cell_index: int, wait_seconds: float = OUTPUT_WAIT_DELAY) → str
- 获取代码单元格的组合文本输出，短暂等待（wait_seconds）。返回输出字符串或状态消息。
delete_cell(cell_index: int) → str
- 根据索引删除特定单元格。
move_cell(from_index: int, to_index: int) → str
- 使用简单的删除/重新插入方法移动单元格，以提高实时渲染稳定性。
search_notebook_cells(search_string: str, case_sensitive: bool = False) → List[Dict[str, Any]]
- 在所有单元格源中搜索 search_string。返回匹配单元格列表 [{'index', 'cell_type', 'source'}]。
split_cell(cell_index: int, line_number: int) → str
- 在特定行号（从 1 开始）处拆分单元格。使用稳健的 Yjs 类型创建。
get_all_cells() → list[dict[str, Any]]
- 获取所有单元格的信息 [{'index', 'cell_type', 'source', 'execution_count'}]。将 Yjs 类型转换为 Python 类型。
edit_cell_source(cell_index: int, new_content: str) → str
- 替换特定单元格的源内容。使用正确的 Yjs 文本 API。
get_kernel_variables(wait_seconds: int = 2) → str
- 使用 %whos 列出内核命名空间中的变量。创建/执行/删除临时单元格。
get_all_outputs() → dict[int, str]
- 获取所有代码单元格的输出。返回字典 {index: output_string} 或类似 [无输出]，[未执行] 的状态。
install_package(package_name: str, timeout_seconds: int = 60) → str
- 使用 !pip install 在内核中安装包。创建/执行/删除临时单元格。输出包括 pip 日志。
list_installed_packages(wait_seconds: int = 5) → str
- 使用 !pip list 列出已安装的包。创建/执行/删除临时单元格。

故障排除

如果在设置或使用过程中遇到问题，请查阅详细的故障排除指南，其中包含了调试期间找到的解决方案。

➡️ TROUBLESHOOTING.md

从源码构建

你可以直接从源码构建 Docker 镜像（包括必要的补丁）：

# 确保你在项目的根目录（Dockerfile 所在的位置）
docker build -t jupyter-mcp-server:latest .

许可证和版权

这是一个由 Datalayer, Inc. 原创的 jupyter-mcp-server 的扩展分支。这个版本经过大量扩展和调试，增加了许多工具（超过 15 种工具，而原始版本只有 2-3 种），用于操纵笔记本、执行代码、管理文件和与内核互动。

此项目根据 BSD 3-Clause 许可证发布。详见 LICENSE 文件中的完整文本。

版权 (c) 2.023-2024 Datalayer, Inc.（原始作品）
版权 (c) 2025 Alexander Isaev（修改和补充）