使用说明

项目简介

Jupyter Earth MCP Server 是一个实现了 Model Context Protocol (MCP) 协议的服务器，旨在为大型语言模型（LLM）客户端提供在 Jupyter Notebook 环境中进行地球科学数据分析的能力。它通过 MCP 协议标准化的方式，使得 LLM 可以远程调用 Jupyter Notebook 的功能，尤其专注于提供下载 NASA Earthdata 地球科学数据的工具。

主要功能点

工具注册与执行: 提供 'download_earth_data_granules' 工具，允许 LLM 客户端指示服务器在 Jupyter Notebook 中执行代码，从而实现地球科学数据的下载。
Jupyter Notebook 集成: 服务器核心功能是控制远程 Jupyter Notebook，利用 Notebook 的计算和环境能力执行数据下载任务。
MCP 协议支持: 遵循 MCP 协议规范，通过 JSON-RPC 与客户端通信，提供标准化的上下文服务接口。
Docker 部署: 提供 Docker 镜像，方便用户快速部署和使用服务器。

安装步骤

安装 Python 包: 如果需要从源码构建或本地运行，请确保安装以下 Python 包：

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

构建 Docker 镜像 (可选): 如果选择 Docker 部署，可以从源码构建 Docker 镜像：
```
make build-docker
```
或者直接使用预构建的 Docker 镜像 'datalayer/jupyter-earth-mcp-server:latest'。

服务器配置

Jupyter Earth MCP Server 通常以 Docker 容器方式运行，并需要与 MCP 客户端（例如 Claude Desktop）配合使用。以下是配置 MCP 客户端连接到 Jupyter Earth MCP Server 的关键信息。你需要将这些配置添加到 MCP 客户端的配置文件中 (例如 Claude Desktop 的 'claude_desktop_config.json')。

配置信息 (JSON 格式):

{
  "mcpServers": {
    "jupyter-earth": {  // 服务器名称，可以自定义，用于在客户端中标识
      "command": "docker",  // 启动服务器的命令，这里使用 Docker
      "args": [  // 命令参数
        "run",
        "-i",  // 保持 STDIN 打开，即使未连接
        "--rm", // 容器退出时自动删除
        "-e",  // 设置环境变量
        "SERVER_URL", // JupyterLab 服务器的 URL
        "-e",
        "TOKEN",  // JupyterLab 的访问 Token
        "-e",
        "NOTEBOOK_PATH", // 要操作的 Jupyter Notebook 文件路径
        "datalayer/jupyter-earth-mcp-server:latest" // Docker 镜像名称
      ],
      "env": {  // 环境变量
        "SERVER_URL": "http://host.docker.internal:8888", //  **[需要根据你的 JupyterLab 实际地址修改]**  如果 JupyterLab 运行在 Docker 外部，并且与 MCP 客户端在同一台机器上，通常可以使用 'http://localhost:8888'。如果 JupyterLab 运行在 Docker 容器内，并且需要从宿主机访问，可能需要使用 'http://host.docker.internal:8888' (Docker for Mac/Windows) 或 'http://localhost:8888' (Linux 且 Docker 使用 host 网络模式)。
        "TOKEN": "MY_TOKEN",  // **[需要替换为你的 JupyterLab 访问 Token]**  在启动 JupyterLab 时通过 '--IdentityProvider.token' 指定的 Token。
        "NOTEBOOK_PATH": "notebook.ipynb"  // **[可选，指定要操作的 Notebook 文件路径]**  相对于 JupyterLab 启动目录的 Notebook 文件路径。默认为 'notebook.ipynb'。
      }
    }
  }
}

Linux 平台特殊配置 (如果 MCP 客户端和 JupyterLab 运行在同一 Linux 宿主机):

如果 MCP 客户端 (如 Claude Desktop Linux 非官方构建版) 和 JupyterLab 运行在同一 Linux 宿主机，并且需要通过 'localhost' 访问 JupyterLab，可能需要在 Docker 命令的 'args' 中添加 '--network=host'，并将 'SERVER_URL' 设置为 'http://localhost:8888'。具体配置请参考 README 中 Linux 平台的 Claude 配置示例。

基本使用方法

启动 JupyterLab: 确保 JupyterLab 服务器已启动，并记录其 URL 和 Token。启动命令示例：

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

配置 MCP 客户端: 将上述 JSON 配置信息添加到你的 MCP 客户端配置文件中，并根据实际情况修改 'SERVER_URL'、'TOKEN' 和 'NOTEBOOK_PATH'。
在 MCP 客户端中使用工具: 在 MCP 客户端中，你可以调用 'jupyter-earth' 服务器提供的 'download_earth_data_granules' 工具。该工具允许你指定文件夹名称、数据集短名称、下载数量以及可选的时间范围和 bounding box，从而在 Jupyter Notebook 中自动生成代码并执行，下载指定的地球科学数据。

'download_earth_data_granules' 工具参数说明:

'folder_name' (string): 本地文件夹名称，用于保存下载的数据。
'short_name' (string): 要下载的 Earthdata 数据集短名称。
'count' (int): 要下载的数据颗粒数量。
'temporal' (tuple, 可选): 时间范围，格式为 '(date_from, date_to)'。
'bounding_box' (tuple, 可选): 地理 bounding box，格式为 '(lower_left_lon, lower_left_lat, upper_right_lon, upper_right_lat)'。

例如，在 Claude Desktop 中，你可以指示其使用 'jupyter-earth' 服务器的 'download_earth_data_granules' 工具，并提供相应的参数，即可在 Jupyter Notebook 中触发数据下载操作。

关键词