内容
<!-- omit in toc -->
# 🪐🔧 Jupyter MCP 服务器
**为 AI 开发的 MCP 服务器，用于实时连接和管理 Jupyter Notebooks**
</div>
> [!NOTE]
> **我们需要您的反馈！**
>
> 我们正在积极开发对 **JupyterHub** 和 **Google Colab** 部署的支持。如果您正在使用或计划在这些平台上使用 Jupyter MCP 服务器，我们希望听到您的意见！
>
> - 🏢 **JupyterHub 用户**：分享您的部署设置和要求
> - 🌐 **Google Colab 用户**：帮助我们了解您的使用场景和工作流程
>
> 在我们的 [社区页面](https://jupyter-mcp-server.datalayer.tech/community) 中加入讨论 - 您的反馈将帮助我们优先考虑功能并确保这些集成能够无缝地满足您的需求。
## 📖 目录
- [关键功能](#-关键功能)
- [MCP 概述](#-mcp-概述)
- [快速入门](#-快速入门)
- [最佳实践](#-最佳实践)
- [贡献](#-贡献)
- [资源](#-资源)
## 🚀 关键功能
- ⚡ **实时控制**：即时查看笔记本更改。
- 🔁 **智能执行**：根据单元格输出反馈自动调整单元格运行失败时的执行。
- 🧠 **上下文感知**：理解整个笔记本上下文以进行更相关的交互。
- 📊 **多模态支持**：支持多种输出类型，包括图像、绘图和文本。
- 📚 **多笔记本支持**：无缝切换多个笔记本。
- 🎨 **JupyterLab 集成**：增强的 UI 集成，如自动打开笔记本。
- 🤝 **MCP 兼容**：与任何 MCP 客户端（如 Claude Desktop、Cursor、Windsurf 等）配合使用。
兼容任何 Jupyter 部署（本地、JupyterHub ...）和 [Datalayer](https://datalayer.ai) 托管的笔记本。
## 🔧 MCP 概述
### 🔧 工具概述
服务器提供了一套丰富的工具用于与 Jupyter 笔记本交互，分类如下。
有关每个工具的详细信息、参数和返回值，请参阅 [官方工具文档](https://jupyter-mcp-server.datalayer.tech/tools).
#### 服务器管理工具
| 名称 | 描述 |
| :--------------- | :----------------------------------------------------------------------------------------- |
| `list_files` | 列出 Jupyter 服务器文件系统中的文件和目录。 |
| `list_kernels` | 列出 Jupyter 服务器上所有可用的和正在运行的内核会话。 |
| `connect_to_jupyter` | 动态连接到 Jupyter 服务器而无需重启 MCP 服务器。 *在作为 Jupyter 扩展运行时不可用。适用于动态切换服务器或避免硬编码配置。* [阅读更多](https://jupyter-mcp-server.datalayer.tech/reference/tools/#3-connect_to_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 模式时可用。默认情况下已启用。*
当在 JupyterLab 模式下运行时，Jupyter MCP 服务器与 [jupyter-mcp-tools](https://github.com/datalayer/jupyter-mcp-tools) 集成，以将额外的 JupyterLab 命令公开为 MCP 工具。默认情况下，以下工具已启用：
| 名称 | 描述 |
| :---------------------------- | :--------------------------------------------------------------------------------- |
| `notebook_run-all-cells` | 顺序执行当前笔记本中的所有单元格 |
| `notebook_get-selected-cell` | 获取当前选定单元格的信息 |
<details>
<summary><strong>📚 了解如何自定义附加工具</strong></summary>
您现在可以使用 `allowed_jupyter_mcp_tools` 配置参数自定义哪些 `jupyter-mcp-tools` 工具可用。这允许您启用额外的笔记本操作、控制台命令、文件管理工具等。
```bash
# 示例：通过命令行启用附加工具
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"
```
有关可用工具的完整列表和详细的配置说明，请参阅 [附加工具文档](https://jupyter-mcp-server.datalayer.tech/reference/tools-additional)。
</details>
### 📝 提示概述
服务器还支持 MCP 的 [提示功能](https://modelcontextprotocol.io/specification/2025-06-18/server/prompts)，为用户提供了一种与 Jupyter 笔记本交互的便捷方式。
| 名称 | 描述 |
| :------------- | :--------------------------------------------------------------------------------- |
| `jupyter-cite` | 从指定笔记本中引用特定单元格（类似于 Coding IDE 或 CLI 中的 `@`） |
有关每个提示、其输入参数和返回内容的详细信息，请参阅 [官方提示文档](https://jupyter-mcp-server.datalayer.tech/reference/prompts)。
## 🏁 快速入门
有关综合设置说明 - 包括 `Streamable HTTP` 传输、作为 Jupyter 服务器扩展运行和高级配置 - 请查看 [我们的文档](https://jupyter-mcp-server.datalayer.tech/)。或者，使用以下内容快速入门 `JupyterLab` 和 `STDIO` 传输。
### 1. 设置环境
```bash
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]
> 要确认您的环境是否正确配置：
> 1. 在 JupyterLab 中打开笔记本
> 2. 在任意单元格中输入一些内容（代码或 Markdown）
> 3. 观察标签指示器：您应该在笔记本名称旁边看到一个“×”，指示有未保存的更改
> 4. 等待几秒钟 - “×”应该自动更改为“●”，而无需手动保存
>
> 此自动保存行为确认实时协作功能正常工作，这对于 MCP 服务器集成至关重要。
### 2. 启动 JupyterLab
```bash
# 在端口 8888 上启动 JupyterLab，允许从任何 IP 地址访问并设置令牌
jupyter lab --port 8888 --IdentityProvider.token MY_TOKEN --ip 0.0.0.0
```
> [!NOTE]
> 如果您通过 JupyterHub 而非 JupyterLab 运行笔记本，请参考我们的 [JupyterHub 设置指南](https://jupyter-mcp-server.datalayer.tech//providers/jupyterhub-streamable-http/).
### 3. 配置首选 MCP 客户端
接下来，配置您的 MCP 客户端以连接到服务器。我们提供两种主要方法 - 请选择最适合您的方法：
- **📦 使用 `uvx`（推荐快速入门）**：一种使用 `uv` 的轻量级快速方法。适用于本地开发和首次用户。
- **🐳 使用 `Docker`（推荐生产环境）**：一种容器化方法，确保环境一致且隔离，适用于生产或复杂设置。
<details>
<summary><b>📦 使用 uvx（快速入门）</b></summary>
首先，安装 `uv`:
```bash
pip install uv
uv --version
# 应为 0.6.14 或更高
```
参见 [uv 安装](https://docs.astral.sh/uv/getting-started/installation/) 的更多详细信息。
然后，配置您的客户端：
```json
{
"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 上：**
```json
{
"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 上：**
```json
{
"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]
>
> 1. **端口配置**：确保 `jupyter lab` 命令中使用的端口与您的 Jupyter URL 中的端口匹配。为了简化配置，请在 `JUPYTER_URL` 中设置此端口。
> 1. **服务器分离**：当两个服务都在同一服务器上时使用 `JUPYTER_URL`，或为高级部署设置单独的变量。不同的 URL 变量存在，因为某些部署将笔记本存储（`DOCUMENT_URL`）与内核执行（`RUNTIME_URL`）分开。
> 1. **身份验证**：在大多数情况下，文档和运行时服务使用相同的身份验证令牌。使用 `JUPYTER_TOKEN` 进行简化配置，或分别设置 `DOCUMENT_TOKEN` 和 `RUNTIME_TOKEN` 以使用不同的凭证。
> 1. **笔记本路径**：`DOCUMENT_ID` 参数指定 MCP 客户端默认连接到的笔记本路径。它应相对于启动 JupyterLab 的目录。如果省略 `DOCUMENT_ID`，MCP 客户端可以自动列出 Jupyter 服务器上的所有可用笔记本，允许您通过提示交互式地选择一个。
> 1. **图像输出**：如果您的 LLM 不支持多模态理解，请将 `ALLOW_IMG_OUTPUT` 设置为 `false`。
有关配置各种 MCP 客户端（包括 [Claude Desktop](https://jupyter-mcp-server.datalayer.tech/clients/claude_desktop)、[VS Code](https://jupyter-mcp-server.datalayer.tech/clients/vscode)、[Cursor](https://jupyter-mcp-server.datalayer.tech/clients/cursor)、[Cline](https://jupyter-mcp-server.datalayer.tech/clients/cline) 和 [Windsurf](https://jupyter-mcp-server.datalayer.tech/clients/windsurf)）的详细说明，请参阅 [客户端文档](https://jupyter-mcp-server.datalayer.tech/clients)。
## ✅ 最佳实践
- 与支持多模态输入的 LLM（例如 Gemini 2.5 Pro）交互，以充分利用先进的多模态理解能力。
- 使用支持返回图像数据并能解析它的 MCP 客户端（例如 Cursor、Gemini CLI 等），因为某些客户端可能不支持此功能。
- 将复杂任务（例如整个数据科学工作流程）分解为多个子任务（例如数据清理、特征工程、模型训练、模型评估等），并逐步执行它们。
- 提供清晰的结构化提示和规则（👉 访问我们的 [提示模板](prompt/README.md) 以开始）
- 提供尽可能多的上下文（例如已安装的包、现有数据集的字段解释、当前工作目录、详细的任务要求等）。
## 🤝 贡献
我们欢迎各种形式的贡献！以下是一些示例：
- 🐛 错误修复
- 📝 现有功能的改进
- 🔧 新功能开发
- 📚 文档改进和提示模板
有关如何开始开发和提交贡献的详细说明，请参阅我们的 [**贡献指南**](CONTRIBUTING.md).
## 📚 资源
寻找有关 Jupyter MCP 服务器的博客文章、视频或其他材料？
👉 访问我们的文档中的 [**资源部分**](https://jupyter-mcp-server.datalayer.tech/resources) 以获取更多信息！
