data-wise-jupyter-mcp-server 2.1.0
Jupyter Lab MCP Server - 提供远程控制 Jupyter Lab 的 MCP 服务
License: MIT
Requires Python: >=3.8
Keywords: fastmcp, jupyter, lab, mcp, notebook, remote

# DataWise Jupyter Lab MCP Server

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

## 功能特性

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

## 安装

```bash
pip install data-wise-jupyter-mcp-server
```

## 使用方法

### 会话模式（唯一模式）

```python
# 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()
```

### 错误处理

如果未先连接就调用其他工具，会收到错误提示：
```json
{
  "success": false,
  "error": "未连接到服务器，请先调用 connect_jupyter"
}
```

### 启动 MCP 服务器

```bash
data-wise-jupyter-mcp-server
```

或者

```bash
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 服务器允许远程访问：

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

### 获取访问令牌

启动 Jupyter Lab 时，会在控制台显示带有 token 的 URL，例如：
```
http://localhost:8888/lab?token=4aa4a5e0aec1f504f1738921c9c823ec28515c72bb5d7247
```

token 就是 `4aa4a5e0aec1f504f1738921c9c823ec28515c72bb5d7247`

### 文件操作示例 🆕

```python
# 下载文件到本地
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/"
})
```

## 开发

### 环境设置

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

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

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

### 运行测试

```bash
pytest
```

## API 参考

### 错误处理

所有工具返回的 JSON 格式：

成功响应：
```json
{
    "success": true,
    "data": {...},
    "message": "操作成功"
}
```

错误响应：
```json
{
    "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