DataWise Jupyter Lab MCP Server

提供远程控制 Jupyter Lab 的 MCP (Model Context Protocol) 服务。

功能特性

• 🔗 远程连接: 连接到远程或本地 Jupyter Lab 服务器
• 📓 笔记本管理: 创建、查看、列出笔记本
• ⚡ 代码执行: 在笔记本中执行 Python 代码
• 🔄 内核控制: 管理和重启 Jupyter 内核
• 📊 服务器监控: 获取服务器状态和会话信息
• 📥 文件下载: 通过内容 API 下载文件到本地
• 📁 目录浏览: 列出远程目录内容
• 📄 文件信息: 获取文件元数据而不下载内容
• 🔧 会话管理: 一次连接，多次使用，无需重复传递参数

安装

pip install data-wise-jupyter-mcp-server

使用方法

会话模式（唯一模式）

# 1. 首先连接到 Jupyter Lab 服务器
connect_jupyter({
    "url": "http://localhost:8888",
    "token": "your_token_here"
})

# 2. 检查连接状态和服务器信息
get_connection_status({"include_server_info": true})

# 3. 使用各种功能（无需传递连接参数）
manage_notebook({"action": "list"})  # 列出笔记本

manage_notebook({
    "action": "execute",
    "path": "analysis.ipynb",
    "code": "print('Hello World')"
})  # 执行代码

manage_file({
    "action": "download",
    "file_path": "data.csv",
    "local_path": "./data.csv"
})  # 下载文件

# 4. 完成后断开连接
disconnect_jupyter()

错误处理

如果未先连接就调用其他工具，会收到错误提示：

{
  "success": false,
  "error": "未连接到服务器，请先调用 connect_jupyter"
}

启动 MCP 服务器

data-wise-jupyter-mcp-server

或者

datawise-jupyter-mcp

可用工具

0. 连接管理 🆕

• connect_jupyter - 连接并保存会话配置
  • 一次性设置连接参数，后续操作无需重复传递
• disconnect_jupyter - 断开连接并清除会话配置
• get_connection_status - 获取连接状态和服务器信息
  • include_server_info=true: 包含详细服务器信息

1. 笔记本管理 🔄

• manage_notebook - 统一的笔记本管理工具
  • action="list": 列出所有笔记本
  • action="create": 创建新笔记本
  • action="get_content": 获取笔记本内容
  • action="execute": 执行代码

2. 内核管理 🔄

• manage_kernel - 统一的内核管理工具
  • action="list": 列出所有内核
  • action="restart": 重启内核

3. 文件操作 🔄

• manage_file - 统一的文件管理工具
  • action="info": 获取文件信息
  • action="download": 下载文件到本地

4. 目录浏览

• list_directory_contents - 列出目录内容
  • 浏览远程目录结构

🔄 合并优化说明

为了简化使用，我们将相关功能合并到统一的管理工具中：

• 笔记本操作 → manage_notebook (4合1)
• 内核操作 → manage_kernel (2合1)
• 文件操作 → manage_file (2合1)

配置

Jupyter Lab 服务器设置

确保你的 Jupyter Lab 服务器允许远程访问：

jupyter lab --no-browser --port=8888 --ip=0.0.0.0

获取访问令牌

启动 Jupyter Lab 时，会在控制台显示带有 token 的 URL，例如：

http://localhost:8888/lab?token=4aa4a5e0aec1f504f1738921c9c823ec28515c72bb5d7247

token 就是 4aa4a5e0aec1f504f1738921c9c823ec28515c72bb5d7247

文件操作示例 🆕

# 下载文件到本地
manage_file({
    "action": "download",
    "file_path": "data/report.csv",
    "local_path": "./downloaded_report.csv"
})

# 获取文件信息
manage_file({
    "action": "info",
    "file_path": "analysis.ipynb"
})

# 列出目录内容
list_directory_contents({
    "dir_path": "data/"
})

开发

环境设置

# 克隆仓库
git clone https://github.com/datawisecenter/jupyter-mcp-server.git
cd jupyter-mcp-server

# 安装依赖
pip install -r requirements.txt

# 安装为开发版本
pip install -e .

运行测试

pytest

API 参考

错误处理

所有工具返回的 JSON 格式：

成功响应：

{
    "success": true,
    "data": {...},
    "message": "操作成功"
}

错误响应：

{
    "success": false,
    "error": "错误信息",
    "data": null
}

支持的 Jupyter Lab 版本

• Jupyter Lab 3.x
• Jupyter Lab 4.x

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！

联系方式

• 邮箱: contact@datawisecenter.com
• GitHub: https://github.com/datawisecenter/jupyter-mcp-server