🚀 Jupyter MCP 服务器客户端

此项目提供了一个基于 Docker 的客户端，用于连接支持多协作协议的 Jupyter 服务器。特别适用于在 Claude 桌面环境下的 Windows 和 Mac 用户，为其带来便捷的使用体验。

🚀 快速开始

本项目的客户端可帮助你在特定环境下连接 Jupyter 服务器，以下是详细的使用步骤。

✨ 主要特性

• 基于 Docker 构建，方便部署和使用。
• 支持多协作协议的 Jupyter 服务器连接。
• 适用于 Windows 和 Mac 在 Claude 桌面环境下使用。

📦 安装指南

先决条件

• Python 3.12.10
• Docker
• Git

安装步骤

1. 设置 Python 环境

# 创建并激活虚拟环境
python3.12 -m venv env
source env/bin/activate  # Windows: env\Scripts\activate

# 安装包管理器
pip install uv

# 安装所需包
uv pip install jupyterlab jupyter-collaboration ipykernel pycrdt
uv pip install jupyter-nbmodel-client jupyter_kernel_client

# 修复依赖项（兼容性要求）
pip uninstall -y jupyter_server_ydoc pycrdt
uv pip install jupyter_server_ydoc pycrdt

2. 创建您的笔记本

# 克隆仓库 -> 必须要进行此步骤
git clone https://github.com/kshitijdesai99/jupyter_mcp_server_kshitij.git
cd jupyter_mcp_server_kshitij
touch notebook.ipynb

3. 启动 Jupyter 服务器

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

⚠️ 重要提示

将 MY_TOKEN 替换为您喜欢的认证令牌，或保持原样。

4. 如果出现 tornado.websocket.WebSocketClosedError 错误（适用于 Mac）

• 删除 notebook.ipynb 文件
• 在 Jupyter 服务器中创建一个新的笔记本，并将其重命名为 notebook.ipynb

Docker 指令

构建 Docker 镜像

docker build -t notebook-client .

运行客户端容器 --> 仅用于测试，不需要用于 mcp

docker run \
  -e NOTEBOOK_PATH="notebook.ipynb" \
  -e SERVER_URL="http://host.docker.internal:8888" \
  -e TOKEN="MY_TOKEN" \
  notebook-client

⚠️ 重要提示

当从不同目录运行时，请使用完整路径到您的笔记本文件。

Claude 桌面集成

将此配置添加到您的 Claude 桌面 config.json 文件中：

"jupyter": {
    "command": "docker",
    "args": [
      "run",
      "--rm",
      "-i",
      "-e", "NOTEBOOK_PATH=notebook.ipynb",
      "-e", "SERVER_URL=http://host.docker.internal:8888",
      "-e", "TOKEN=MY_TOKEN",
      "notebook-client"
    ]
}

⚠️ 重要提示

无需更新笔记本路径

💡 使用建议

故障排除

• 确保 Jupyter 服务器在连接客户端之前正在运行。
• 验证服务器和客户端配置中的令牌是否匹配。
• Windows 路径在 Docker 中，请使用双反斜杠，如示例所示。