Jupyter-MCP-服务器

Name: Jupyter-MCP-服务器
Author: datalayer

作者：datalayer784 星标更新：2025-11-19

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

项目介绍

  ~ 版权所有 (c) 2024- Datalayer, Inc.
  ~
  ~ BSD 3-Clause 许可证

🪐✨ Jupyter MCP 服务器

一个为AI开发的MCP服务器，用于实时连接和管理Jupyter笔记本

由Datalayer开发

Jupyter MCP 服务器演示

</div>

📖 目录

关键特性
MCP 概览
快速开始
最佳实践
贡献
资源

🚀 关键特性

⚡ 实时控制： 即时查看笔记本的变化。
🔁 智能执行： 自动调整失败的单元格运行。
🧠 上下文感知： 理解整个笔记本的上下文以进行更相关的交互。
📊 多模态支持： 支持不同类型的输出，包括图像、图表和文本。
📚 多笔记本支持： 在多个笔记本之间无缝切换。
🎨 JupyterLab 集成： 增强的UI集成，如自动打开笔记本。
🤝 MCP 兼容： 与任何MCP客户端兼容，例如Claude Desktop、Cursor、Windsurf等。

兼容任何Jupyter部署（本地、JupyterHub等）以及Datalayer托管的笔记本。

✨ MCP 概览

🔧 工具概述

服务器提供了一套丰富的工具来与Jupyter笔记本互动，分为以下几类：

服务器管理工具

名称	描述
`list_files`	列出Jupyter服务器文件系统中的文件和目录。
`list_kernels`	列出Jupyter服务器上所有可用和正在运行的内核会话。

多笔记本管理工具

名称	描述
`use_notebook`	连接到一个笔记本文件，创建一个新的笔记本或在多个笔记本之间切换。
`list_notebooks`	列出Jupyter服务器上所有可用的笔记本及其状态。
`restart_notebook`	重启特定管理笔记本的内核。
`unuse_notebook`	断开与特定笔记本的连接并释放其资源。
`read_notebook`	读取笔记本单元格源内容，可以选择简洁或详细的格式选项。

单元格操作和执行工具

名称	描述
`read_cell`	读取单个单元格的完整内容（元数据、源代码和输出）。
`insert_cell`	在指定位置插入新的代码或Markdown单元格。
`delete_cell`	删除指定索引处的单元格。
`overwrite_cell_source`	覆盖现有单元格的源代码。
`execute_cell`	执行单元格，支持超时，支持多模态输出，包括图像。
`insert_execute_code_cell`	插入新的代码单元格并一步执行。
`execute_code`	直接在内核中执行代码，支持魔术命令和shell命令。

JupyterLab 集成

仅当启用JupyterLab模式时可用，默认情况下已启用。

名称	描述
`notebook_run-all-cells`	顺序执行当前笔记本中的所有单元格。

有关每个工具的详细信息，请参阅官方工具文档。

📝 提示概述

服务器还支持MCP的prompt功能，为用户提供与Jupyter笔记本互动的便捷方式。

名称	描述
`jupyter-cite`	引用特定笔记本中的特定单元格（类似于Coding IDE或CLI中的`@`）

有关每个提示的详细信息，请参阅官方提示文档。

🏁 快速开始

对于全面的设置说明——包括Streamable HTTP传输、作为Jupyter服务器扩展运行和高级配置——请查阅我们的文档。或者，您可以快速开始使用JupyterLab和STDIO传输，如下所示。

1. 设置您的环境

pip install jupyterlab==4.4.1 jupyter-collaboration==4.0.2 jupyter-mcp-tools>=0.1.4 ipykernel
pip uninstall -y pycrdt datalayer_pycrdt
pip install datalayer_pycrdt==0.12.17

[!TIP] 确认您的环境正确配置：

在JupyterLab中打开一个笔记本。

在任意单元格（代码或Markdown）中输入一些内容。

观察标签指示器：您应该看到笔记本名称旁边出现一个“×”，表示未保存更改。

等待几秒钟——“×”应自动变为“●”，无需手动保存。

这种自动保存行为确认了实时协作功能正常工作，这对于MCP服务器集成至关重要。

2. 启动JupyterLab

# 在8888端口启动JupyterLab，允许从任何IP访问，并设置一个令牌
jupyter lab --port 8888 --IdentityProvider.token MY_TOKEN --ip 0.0.0.0

[!NOTE] 如果您通过JupyterHub而不是上述的JupyterLab运行笔记本，您应该：

在单用户环境中设置环境变量JUPYTERHUB_ALLOW_TOKEN_IN_URL=1。

确保您的API令牌（MY_TOKEN）在Hub中具有access:servers范围。

3. 配置您首选的MCP客户端

接下来，配置您的MCP客户端以连接到服务器。我们提供了两种主要方法——选择最适合您需求的方法：

📦 使用uvx（推荐快速开始）： 使用uv的轻量级和快速方法。适合本地开发和初学者。
🐳 使用Docker（推荐生产环境）： 容器化方法确保一致且隔离的环境，适用于生产或复杂设置。

首先，安装uv：

pip install uv
uv --version
# 应该是0.6.14或更高版本

更多详情请参阅uv安装。

然后，配置您的客户端：

{
  "mcpServers": {
    "jupyter": {
      "command": "uvx",
      "args": ["jupyter-mcp-server@latest"],
      "env": {
        "JUPYTER_URL": "http://localhost:8888",
        "JUPYTER_TOKEN": "MY_TOKEN",
        "ALLOW_IMG_OUTPUT": "true"
      }
    }
  }
}

</details> <details> <summary><b>🐳 使用 Docker（生产环境）</b></summary>

在macOS和Windows上：

{
  "mcpServers": {
    "jupyter": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "JUPYTER_URL",
        "-e", "JUPYTER_TOKEN",
        "-e", "ALLOW_IMG_OUTPUT",
        "datalayer/jupyter-mcp-server:latest"
      ],
      "env": {
        "JUPYTER_URL": "http://host.docker.internal:8888",
        "JUPYTER_TOKEN": "MY_TOKEN",
        "ALLOW_IMG_OUTPUT": "true"
      }
    }
  }
}

在Linux上：

{
  "mcpServers": {
    "jupyter": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "JUPYTER_URL",
        "-e", "JUPYTER_TOKEN",
        "-e", "ALLOW_IMG_OUTPUT",
        "--network=host",
        "datalayer/jupyter-mcp-server:latest"
      ],
      "env": {
        "JUPYTER_URL": "http://localhost:8888",
        "JUPYTER_TOKEN": "MY_TOKEN",
        "ALLOW_IMG_OUTPUT": "true"
      }
    }
  }
}

</details>

[!TIP]

端口配置：确保Jupyter URL中的port与jupyter lab命令中使用的端口匹配。为了简化配置，可以在JUPYTER_URL中设置此值。

服务器分离：当两个服务在同一服务器上时使用JUPYTER_URL，或为高级部署设置单独的变量。不同的URL变量存在是因为某些部署将笔记本存储（DOCUMENT_URL）与内核执行（RUNTIME_URL）分开。

身份验证：大多数情况下，文档和运行时服务使用相同的认证令牌。使用JUPYTER_TOKEN进行简化配置，或分别设置DOCUMENT_TOKEN和RUNTIME_TOKEN以使用不同的凭证。

笔记本路径：DOCUMENT_ID参数指定了MCP客户端默认连接的笔记本路径。它应该是JupyterLab启动的目录下的相对路径。如果您省略DOCUMENT_ID，MCP客户端可以自动列出Jupyter服务器上的所有可用笔记本，让您可以通过提示选择一个。

图像输出：如果您的LLM不支持多模态理解，请将ALLOW_IMG_OUTPUT设置为false。

有关配置各种MCP客户端的详细说明——包括Claude Desktop、VS Code、Cursor、Cline和Windsurf——请参阅客户端文档。

✅ 最佳实践

与支持多模态输入的LLM（如Gemini 2.5 Pro）互动，充分利用先进的多模态理解能力。
使用支持返回图像数据并能解析它的MCP客户端（如Cursor、Gemini CLI等），因为某些客户端可能不支持此功能。
将复杂的任务（如整个数据科学工作流程）分解为多个子任务（如数据清洗、特征工程、模型训练、模型评估等），并逐步执行。
提供清晰结构化的提示和规则（👉 访问我们的提示模板以开始）
提供尽可能多的上下文（如已安装的包、现有数据集的字段解释、当前工作目录、详细的任务要求等）。

🤝 贡献

我们欢迎各种形式的贡献！这里是一些例子：

🐛 Bug修复
📝 现有功能的改进
✨ 新功能开发
📚 文档改进和提示模板

有关如何开始开发和提交贡献的详细说明，请参阅我们的贡献指南。

我们的贡献者

📚 资源

寻找关于Jupyter MCP服务器的博客文章、视频或其他材料？

👉 访问我们的资源部分以获取更多信息！

如果这个项目对您有帮助，请给我们一个⭐️

由Datalayer制作 ❤️

</div>