Jupyter MCP Server

<!--
  ~ Copyright (c) 2023-2024 Datalayer, Inc.
  ~
  ~ BSD 3-Clause License
-->

[![Datalayer](https://assets.datalayer.tech/datalayer-25.svg)](https://datalayer.io)

[![成为赞助者](https://img.shields.io/static/v1?label=成为赞助者&message=%E2%9D%A4&logo=GitHub&style=flat&color=1ABC9C)](https://github.com/sponsors/datalayer)

# 🪐 ✨ Jupyter MCP 服务器

[![Github Actions 状态](https://github.com/datalayer/jupyter-mcp-server/workflows/Build/badge.svg)](https://github.com/datalayer/jupyter-mcp-server/actions/workflows/build.yml)
[![PyPI - 版本](https://img.shields.io/pypi/v/jupyter-mcp-server)](https://pypi.org/project/jupyter-mcp-server)
[![smithery badge](https://smithery.ai/badge/@datalayer/jupyter-mcp-server)](https://smithery.ai/server/@datalayer/jupyter-mcp-server)

Jupyter MCP 服务器是一个 [模型上下文协议](https://modelcontextprotocol.io) (MCP) 服务器实现，它提供与在任何 JupyterLab 中运行的 📓 Jupyter 笔记本的交互（也适用于您的 💻 本地 JupyterLab）。

![Jupyter MCP 服务器](https://assets.datalayer.tech/jupyter-mcp/jupyter-mcp-server-claude-demo.gif)

## 启动 JupyterLab

确保您已安装以下组件。 需要 collaboration 包，因为笔记本上所做的修改可以通过 [Jupyter 实时协作](https://jupyterlab.readthedocs.io/en/stable/user/rtc.html) 看到。

```bash
pip install jupyterlab jupyter-collaboration ipykernel
pip uninstall -y pycrdt datalayer_pycrdt
pip install datalayer_pycrdt

然后，使用以下命令启动 JupyterLab。

jupyter lab --port 8888 --IdentityProvider.token MY_TOKEN --ip 0.0.0.0

您也可以运行 make jupyterlab。

[!NOTE]

--ip 设置为 0.0.0.0，以允许在 Docker 容器中运行的 MCP 服务器访问您的本地 JupyterLab。

与 Claude Desktop 一起使用

可以从此页面下载适用于 macOS 和 Windows 的 Claude Desktop。

对于 Linux，我们成功使用了这个基于 nix 的非官方构建脚本

# ⚠️ 非官方
# 您也可以运行 `make claude-linux`
NIXPKGS_ALLOW_UNFREE=1 nix run github:k3d3/claude-desktop-linux-flake \
  --impure \
  --extra-experimental-features flakes \
  --extra-experimental-features nix-command

要将其与 Claude Desktop 一起使用，请将以下内容添加到您的 claude_desktop_config.json 中（在 MCP 文档网站 上阅读更多信息）。

[!IMPORTANT]

确保 SERVER_URL 和 TOKEN 的端口与 jupyter lab 命令中使用的端口匹配。

NOTEBOOK_PATH 应该相对于 JupyterLab 启动的目录。

macOS 和 Windows 上的 Claude 配置

{
  "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",
        "TOKEN": "MY_TOKEN",
        "NOTEBOOK_PATH": "notebook.ipynb"
      }
    }
  }
}

Linux 上的 Claude 配置

CLAUDE_CONFIG=${HOME}/.config/Claude/claude_desktop_config.json
cat <<EOF > $CLAUDE_CONFIG
{
  "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",
        "TOKEN": "MY_TOKEN",
        "NOTEBOOK_PATH": "notebook.ipynb"
      }
    }
  }
}
EOF
cat $CLAUDE_CONFIG

组件

工具

该服务器目前提供 3 个工具：

1. add_execute_code_cell

• 在 Jupyter 笔记本中添加并执行代码单元格。
• 输入：
  • cell_content(string): 要执行的代码。
• 返回：单元格输出。

2. add_markdown_cell

• 在 Jupyter 笔记本中添加一个 markdown 单元格。
• 输入：
  • cell_content(string): Markdown 内容。
• 返回：成功消息。

3. download_earth_data_granules

   ⚠️ 我们计划将来将此工具迁移到单独的存储库，因为它特定于地理空间分析。

• 在 Jupyter 笔记本中添加一个代码单元格，以下载来自 NASA Earth Data 的地球数据颗粒。
• 输入：
  • folder_name(string): 用于保存数据的本地文件夹名称。
  • short_name(string): 要下载的地球数据集的简称。
  • count(int): 要下载的数据颗粒的数量。
  • temporal (tuple): (可选) 格式为 (date_from, date_to) 的时间范围。
  • bounding_box (tuple): (可选) 格式为 (lower_left_lon, lower_left_lat, upper_right_lon, upper_right_lat) 的边界框。
• 返回：单元格输出。

构建

您可以从源代码构建 Docker 镜像。

make build-docker

通过 Smithery 安装

要通过 Smithery 自动为 Claude Desktop 安装 Jupyter MCP 服务器：

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