🪐🔧 Jupyter MCP 服务器

[!注意] 我们需要您的反馈！

我们正在积极开发对JupyterHub和Google Colab部署的支持。如果您正在使用或计划在这些平台上使用Jupyter MCP服务器，我们非常希望听到您的声音！

• 🏢 JupyterHub用户：分享您的部署设置和需求
• 🌐 Google Colab用户：帮助我们了解您的用例和工作流程

加入我们的社区页面讨论 - 您的反馈将帮助我们优先考虑功能，并确保这些集成能满足您的需求。

📖 目录

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

🚀 关键特性

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

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

🔧 MCP概述

🔧 工具概述

服务器提供了一套丰富的工具用于与Jupyter笔记本交互，分类如下。有关每个工具的详细信息、参数和返回值，请参阅官方工具文档。

服务器管理工具

多笔记本管理工具

单元格操作和执行工具

JupyterLab集成

仅在启用JupyterLab模式时可用。默认启用。

在JupyterLab模式下运行时，Jupyter MCP服务器与jupyter-mcp-tools集成，将额外的JupyterLab命令作为MCP工具公开。默认启用以下工具：

# 示例：通过命令行启用额外工具
jupyter lab --port 4040 --IdentityProvider.token MY_TOKEN --JupyterMCPServerExtensionApp.allowed_jupyter_mcp_tools="notebook_run-all-cells,notebook_get-selected-cell,notebook_append-execute,console_create"

📝 提示概述

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

有关每个提示的更多详情、输入参数和返回内容，请参阅官方提示文档。

🏁 快速开始

有关全面设置说明——包括可流式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

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

1. 在JupyterLab中打开一个笔记本
2. 在任何单元格（代码或Markdown）中输入一些内容
3. 观察标签指示器：您应该会在笔记本名称旁边看到一个"×"，表示未保存的更改
4. 等待几秒钟 - "×"应自动变为"●"，无需手动保存

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

2. 启动JupyterLab

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

[!注意] 如果您通过JupyterHub而非上述JupyterLab运行笔记本，请参考我们的JupyterHub设置指南。

3. 配置您偏好的MCP客户端

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

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

pip install uv
uv --version
# 版本需为0.6.14或更高

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

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

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

[!TIP]

1. 端口配置：确保Jupyter URL中的port与jupyter lab命令使用的端口一致。为简化配置，可在JUPYTER_URL中设置。
2. 服务分离：当两个服务位于同一服务器时使用JUPYTER_URL，高级部署可设置独立变量。不同URL变量的存在是因为某些部署会将笔记本存储(DOCUMENT_URL)与内核执行(RUNTIME_URL)分离。
3. 认证：多数情况下文档和运行时服务使用相同认证令牌。简化配置使用JUPYTER_TOKEN，不同凭证可分别设置DOCUMENT_TOKEN和RUNTIME_TOKEN。
4. 笔记本路径：DOCUMENT_ID参数指定MCP客户端默认连接的笔记本路径，应相对于JupyterLab启动目录。若省略DOCUMENT_ID，MCP客户端会自动列出Jupyter服务器上所有可用笔记本，您可通过提示交互选择。
5. 图像输出：若您的LLM不支持多模态理解，请将ALLOW_IMG_OUTPUT设为false。

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

✅ 最佳实践

• 与支持多模态输入的LLM（如Gemini 2.5 Pro）交互，充分发挥高级多模态理解能力
• 使用支持返回图像数据并能解析的MCP客户端（如Cursor、Gemini CLI等），部分客户端可能不支持此功能
• 将复杂任务（如完整的数据科学工作流）拆分为多个子任务（如数据清洗、特征工程、模型训练、模型评估等）逐步执行
• 提供结构清晰的提示和规则（👉 查看我们的提示模板开始使用）
• 尽可能提供完整上下文（如已安装的软件包、现有数据集的字段说明、当前工作目录、详细的任务需求等）

🤝 贡献指南

我们欢迎各类贡献！包括但不限于：

• 🐛 错误修复
• 📝 现有功能改进
• 🔧 新功能开发
• 📚 文档改进和提示模板

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

贡献者名单

📚 资源

寻找关于Jupyter MCP Server的博客文章、视频或其他资料？

👉 访问文档中的资源专区获取更多内容！