关键词

JupyterNotebook代码执行数据科学编程助手

使用说明

项目简介

Jupyter MCP 服务器是一个基于 Model Context Protocol (MCP) 构建的应用后端，它允许支持 MCP 的大型语言模型（LLM）客户端（如 Goose, Cursor）连接到正在运行的 JupyterLab 实例。通过这种连接，LLM 可以感知和利用 Jupyter 笔记本中的变量状态、环境配置，并直接在笔记本中执行代码、管理单元格（cell），从而提供更智能、更具上下文感知能力的编程辅助体验，特别适用于数据科学和开发工作流程。

主要功能点

  • 笔记本管理： 创建新的 Jupyter 笔记本，或连接到现有笔记本。
  • 单元格操作： 在笔记本中添加、编辑、删除代码或 Markdown 单元格。
  • 代码执行： 在笔记本的 Python 环境中直接执行代码单元格，获取执行结果和输出。
  • 查看源码： 查看整个笔记本或特定单元格的源代码和元数据。
  • 包安装： 在笔记本的 Python 环境中安装所需的 Python 包（通过 uv pip）。
  • 状态感知： 服务器跟踪笔记本的内容变化，确保 LLM 在进行状态依赖的操作前了解最新的笔记本状态。
  • 连接检查： 检查 Jupyter 服务器是否正在运行且可访问。

安装步骤

本项目依赖于 'uv'，请首先确保您已经安装了 'uv'（一个快速的 Python 包安装和管理工具）。安装 'uv' 的方法请参考其官方文档。

安装 'uv' 后，本 MCP 服务器作为一个 'uvx' 可执行的应用。

服务器配置

本 MCP 服务器使用标准输入输出（stdio）作为传输协议。为了让支持 MCP 的客户端连接到此服务器，您需要在客户端中配置服务器的启动命令。

典型的客户端配置需要提供服务器的名称 ('server name')、启动命令 ('command') 及其参数 ('args')。对于 Jupyter MCP 服务器，配置信息如下：

{
  "server name": "jupyter", // 服务器的标识名称
  "command": "uvx", // 启动服务器的命令
  "args": ["mcp-jupyter"] // 传递给命令的参数，即 MCP 服务器的应用名
}

请注意，MCP 客户端界面通常会提供 UI 界面来输入这些配置信息，而不是直接编辑 JSON 文件。您只需在客户端中找到添加或配置 MCP 服务器的地方，输入上述对应的“命令”和“参数”即可。

基本使用方法

  1. 启动 JupyterLab： 本 MCP 服务器需要连接到一个正在运行的 JupyterLab 实例。请确保您已经安装了 'jupyterlab' 和 'ipykernel'，并按照如下示例启动 JupyterLab，使其在特定端口运行并设置好访问令牌。

    # 示例：使用 uv 创建虚拟环境并安装依赖
uv venv
source .venv/bin/activate
uv pip install jupyterlab jupyter-collaboration ipykernel

# 示例：启动 JupyterLab，监听 8888 端口，设置令牌为 BLOCK
# 请确保您启动 JupyterLab 的目录是您希望 MCP 服务器访问笔记本的根目录
jupyter lab --port 8888 --IdentityProvider.token BLOCK --ip 0.0.0.0

    （注意：您可以根据需要修改端口和令牌，但请确保启动 MCP 服务器时使用的 TOKEN 环境变量与此处设置的令牌一致，且客户端配置连接的服务器地址和端口正确。）

  2. 启动 MCP 客户端并连接 MCP 服务器： 启动您支持 MCP 的 LLM 客户端（例如 Goose 或 Cursor）。根据客户端的指引，配置并启动 Jupyter MCP 服务器。通常，客户端会使用您在“服务器配置”步骤中提供的命令 ('uvx mcp-jupyter') 来自动启动并连接到 MCP 服务器。

  3. 通过 LLM 客户端与 Jupyter 交互： 一旦 MCP 服务器启动并连接到 JupyterLab，LLM 客户端就可以利用服务器提供的工具与您的 Jupyter 笔记本进行交互了。您可以在聊天界面中指示 LLM 执行代码、查看笔记本内容、安装包等，LLM 将通过 MCP 协议调用服务器的相应工具来实现这些操作。

    • 首次使用某个笔记本时，LLM 客户端通常会调用服务器的 'notebook' 工具来准备（创建或打开）该笔记本。
    • 后续操作（如添加单元格、执行代码）将通过调用 'add_code_cell', 'execute_cell', 'view_source' 等工具完成。

注意事项

  • MCP 服务器必须能够访问到正在运行的 JupyterLab 实例（通常需要运行在同一机器或可网络访问的环境中）。
  • JupyterLab 的启动目录将成为 MCP 服务器访问笔记本的根目录。MCP 服务器操作的笔记本路径是相对于此根目录的。
  • 请确保 JupyterLab 使用的令牌与 MCP 服务器（通过 TOKEN 环境变量）使用的令牌一致。

信息

分类

开发者工具

访问项目