Jupyter MCP Server Extended

Jupyter MCP扩展

通过模型上下文协议增强Jupyter Notebook交互

 ](https://smithery.ai/server/@itisaevalex/jupyter-mcp-server-extended)

该项目提供了 模型上下文协议（MCP） 该服务器支持AI模型（如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服务器容器（包括必要的补丁）。
• 枕头： 服务器（包含在Docker构建中）需要用于映像处理。
• MCP客户端： 例如 克劳德桌面版.

安装和设置

请仔细遵循以下步骤，根据调试结果创建稳定的环境：

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

打开您的终端（Anaconda Prompt或类似设备）。运行终端 “作为管理员” 可能需要初始 pip 如果您的系统上限制了conda基本权限，则会进行安装，尽管使用专用环境通常可以避免这种情况。

# Create a clean environment (Python 3.10 worked during debugging)
conda create -n jupyter_mcp_env python=3.10 -y

# Activate the environment
conda activate jupyter_mcp_env

记得激活此环境(conda activate jupyter_mcp_env)在任何终端上运行pip或jupyter lab命令之前。

2.安装Jupyter核心组件：

# Use 'python -m pip' to ensure correct pip in the activated env
python -m pip install jupyterlab ipykernel

3.安装特定的jupyter_collaboration版本：

较新的版本在调试过程中引发了问题。需要2.0.1版本。

# Install the required v2.0.1
python -m pip install "jupyter_collaboration==2.0.1"

4.处理pycrdt依赖关系：

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

# Uninstall potentially conflicting versions
python -m pip uninstall -y pycrdt datalayer_pycrdt

# Install the required version
python -m pip install datalayer_pycrdt

5.启用协作扩展：

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

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

6.构建补丁的Docker镜像：

包含的Dockerfile包含调试期间识别的补丁。在本地构建映像：

# Navigate to the directory containing the Dockerfile
# cd /path/to/your/jupyter-mcp-server/
docker build -t jupyter-mcp-server:latest .

7.启动JupyterLab：

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

# Use a strong, unique token!
# --ip=0.0.0.0 allows the Docker container to connect
jupyter lab --port 8888 --IdentityProvider.token YOUR_SECURE_TOKEN --ip 0.0.0.0

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

配置

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

• 服务器URL： 您正在运行的JupyterLab的URL（例如。， http://host.docker.internal:8888 对于Docker桌面Win/Mac， http://localhost:8888 适用于Linux --network=host).请勿在此处包含令牌。
• 令牌： 与一起使用的确切令牌 --IdentityProvider.token JupyterLab。
• 记事本路径： 相对于JupyterLab的起始目录的初始目标笔记本路径（例如。， notebook.ipynb).可通过以下方式更改 set_target_notebook 工具。
• LOG_LEVEL： 服务器日志记录冗长(DEBUG, INFO, WARNING).违约： INFO.
• OUTPUT_WAIT_DELAY： 默认等待时间（秒） get_cell_output默认值：0.5。

使用Claude Desktop

1. 安装克劳德桌面。
2. 定位 claude_desktop_config.json.
3. 添加/修改 mcpServers 块，适应您的操作系统和配置：

Claude配置（macOS/Windows，带Docker桌面）

{
  "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" 
      }
    }
  }
}

克劳德配置（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" 
      }
    }
  }
}

1. 保存配置文件并重新启动Claude Desktop。

可用工具

此服务器提供以下与Jupyter交互的工具：

• list_notebook_directory（） → str

- 列出与当前目标笔记本位于同一位置的文件和目录。目录以/结尾。

• get_file_content（文件路径：str，max_image_dim:int=1024） → str

- 检索文件内容。文本直接返回。如果图像较大，则会调整其大小（保留纵横比，最大尺寸max_image_dim），并作为base64数据URI字符串返回。描述了二进制文件。

• set_target_notebook（new_notebook_path:str） → str

- 更改后续工具调用的目标笔记本文件路径（仅限会话）。路径必须是相对的。

• add_cell（内容：str，单元类型：str，索引：可选\[int\]=无） → str

- 在索引处添加具有指定内容的新单元格（“代码”或“标记”）（如果索引为“无”或无效，则追加）。使用健壮的Yjs类型创建。

• add_code_cell_on_bottom（单元格内容：str） → str

- 在笔记本末尾添加一个代码单元格。

• execute_cell（单元索引：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（单元索引：int） → str

- 按索引删除特定单元格。

• move_cell（从索引int到索引int） → str

- 使用简单的删除/重新插入方法移动单元格，以获得更好的实时渲染稳定性。

• search_notebook_cells（search_string:str，case_sensitive：bool=False） → 列表\[Dict\[str，Any\]\]

- 在所有单元格源中搜索search_string。返回匹配单元格的列表〔｛'index'，'cell_type'，'source'｝〕。

• split_cell（单元索引：int，行号：int） → str

- 在特定行号（从1开始）处拆分单元格。使用健壮的Yjs类型创建。

• get_all_cells（） → list〔dict〔str，Any〕〕

- 检索所有单元格的信息〔｛'index'，'cell_type'，'source'，'execution_count'｝〕。将Yjs类型转换为Python类型。

• edit_cell_source（单元索引：int，新内容：str） → str

- 替换特定单元格的源内容。使用正确的Yjs文本API。

• get_kernel_变量（等待秒数：int=2） → str

- 使用%whos列出内核命名空间中的变量。创建/执行/删除临时单元格。

• get_all_outputs（） → dict\[int，str\]

- 检索所有代码单元格的输出。返回dict{index:output_string}或状态，如\[无输出\]、\[未执行\]。

• 安装包（包名：str，超时秒数：int=60） → str

- 使用将包安装到内核中！pip安装。创建/执行/删除临时单元格。输出包括pip日志。

• list_installed_packages（等待时间：int=5） → str

- 使用列出已安装的软件包！pip列表。创建/执行/删除临时单元格。

故障排除

如果您在安装或使用过程中遇到问题，请参阅详细的故障排除指南，其中包括调试过程中找到的解决方案。

➡️ 故障排除.md

从源头构建

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

# Make sure you are in the project's root directory (where Dockerfile is)
docker build -t jupyter-mcp-server:latest .

许可和版权

这是一个 加长叉 的原件 jupyter-mcp-server 由Datalayer，股份有限公司开发。该版本经过大量扩展和调试，扩展了原始功能，修复了许多问题，并提供了更广泛的工具（与原始2-3相比，有15种以上的工具），用于操作笔记本电脑、执行代码、管理文件和与内核交互。

此项目根据BSD 3条款许可证获得许可。请参阅LICENSE文件以获取全文。

版权属于各贡献者：

• 版权所有（c）2023-2024 Datalayer，股份有限公司（原创作品）
• 版权所有（c）2025 Alexander Isaev（修改和添加）