Jupyter MCP Server 使用说明

项目简介

Jupyter MCP Server 是一个基于 Model Context Protocol (MCP) 构建的服务器，旨在桥接大型语言模型 (LLM) 和 Jupyter Notebook。通过此服务器，LLM 客户端可以远程操控 Jupyter Notebook，实现代码执行、内容编辑和数据访问等功能，从而将 Jupyter Notebook 转变为 AI 驱动的交互式工作空间。

主要功能点

代码执行: 允许 LLM 向 Jupyter Notebook 添加并执行代码单元格，并返回执行结果。
Markdown编辑: 支持 LLM 向 Jupyter Notebook 添加 Markdown 单元格，用于文档编辑和内容创作。
数据下载: 提供下载地球科学数据的工具，方便 LLM 驱动的数据分析和处理流程（该功能未来可能迁移到单独仓库）。

安装步骤

安装 JupyterLab 及依赖: 确保已安装 JupyterLab, jupyter-collaboration 和 ipykernel。

pip install jupyterlab jupyter-collaboration ipykernel

启动 JupyterLab 服务器: 使用以下命令启动 JupyterLab，并设置允许 Docker 容器访问的 IP 地址和 Token。
```
jupyter lab --port 8888 --IdentityProvider.token MY_TOKEN --ip 0.0.0.0
```
注意: 记录 '--port' 和 '--IdentityProvider.token' 的值，后续配置 MCP 客户端时需要使用。

构建 Jupyter MCP Server Docker 镜像 (可选): 如果选择 Docker 部署，可以构建本地镜像。

docker build -t datalayer/jupyter-mcp-server .

通过 Smithery 安装 (推荐): 对于 Claude Desktop 客户端，推荐使用 Smithery 自动安装。

npx -y @smithery/cli install @datalayer/jupyter-mcp-server --client claude

服务器配置

MCP 客户端 (例如 Claude Desktop) 需要配置以下 JSON 对象才能连接到 Jupyter MCP Server。以下配置以 Claude Desktop 的 'claude_desktop_config.json' 为例：

MacOS 和 Windows 配置

{
  "mcpServers": {
    "jupyter": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "SERVER_URL",
        "-e",
        "TOKEN",
        "-e",
        "NOTEBOOK_PATH",
        "datalayer/jupyter-mcp-server:latest"
      ],
      "env": {
        "SERVER_URL": "http://host.docker.internal:8888",  // JupyterLab 服务器 URL，Docker 容器内访问宿主机 JupyterLab
        "TOKEN": "MY_TOKEN",                             // JupyterLab 访问 Token，与启动 JupyterLab 时 '--IdentityProvider.token' 参数一致
        "NOTEBOOK_PATH": "notebook.ipynb"                // 相对于 JupyterLab 启动目录的 Notebook 文件路径
      }
    }
  }
}

Linux 配置

{
  "mcpServers": {
    "jupyter": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "SERVER_URL",
        "-e",
        "TOKEN",
        "-e",
        "NOTEBOOK_PATH",
        "--network=host",
        "datalayer/jupyter-mcp-server:latest"
      ],
      "env": {
        "SERVER_URL": "http://localhost:8888",         // JupyterLab 服务器 URL，宿主机直接访问 JupyterLab
        "TOKEN": "MY_TOKEN",                             // JupyterLab 访问 Token，与启动 JupyterLab 时 '--IdentityProvider.token' 参数一致
        "NOTEBOOK_PATH": "notebook.ipynb"                // 相对于 JupyterLab 启动目录的 Notebook 文件路径
      }
    }
  }
}

配置参数说明:

'"server name"': '"jupyter"'，MCP 服务器的名称，客户端用此名称引用。
'"command"': '"docker"'，运行 MCP 服务器的命令，这里使用 Docker 运行。
'"args"': 运行 'command' 的参数列表。
- '"run", "-i", "--rm"': Docker 运行参数，'-i' 保持标准输入打开，'--rm' 容器退出后自动删除。
- '"-e", "SERVER_URL", ... , "-e", "NOTEBOOK_PATH"': 通过环境变量传递配置信息给 Docker 容器内的 MCP 服务器。
- '"datalayer/jupyter-mcp-server:latest"': Docker 镜像名称，如果本地构建请替换为你的镜像名称。
- '"--network=host"' (仅 Linux): Linux 下使 Docker 容器与宿主机共享网络，允许容器直接访问宿主机的 JupyterLab 服务。
'"env"': 环境变量配置。
- '"SERVER_URL"': JupyterLab 服务器的 URL，需要根据 JupyterLab 实际启动地址配置。Docker 容器内访问宿主机需使用 'host.docker.internal' (MacOS/Windows) 或 'localhost' (Linux)。
- '"TOKEN"': JupyterLab 的访问 Token，与启动 JupyterLab 时设置的 Token 一致。
- '"NOTEBOOK_PATH"': 要操作的 Jupyter Notebook 文件路径，相对于 JupyterLab 启动时的目录。

基本使用方法

配置完成后，LLM 客户端即可通过 MCP 协议与 Jupyter MCP Server 通信。客户端可以调用服务器提供的 Tools，例如：

使用 'add_execute_code_cell' 工具向 Jupyter Notebook 添加并执行代码，例如让 LLM 执行 Python 代码进行数据分析或可视化。
使用 'add_markdown_cell' 工具向 Notebook 添加 Markdown 内容，例如让 LLM 自动生成文档或报告。
使用 'download_earth_data_granules' 工具指示服务器下载地球科学数据到 Notebook 环境，为后续分析做准备。

具体调用方式取决于 LLM 客户端的实现，通常客户端会提供界面或 API 来选择和调用 MCP 服务器提供的 Tools。

关键词