# 🪐 Jupyter MCP Server
专门为AI连接与管理Jupyter Notebook而开发的MCP服务
*由 [ChengJiale150](https://github.com/ChengJiale150) 开发*
[](https://www.python.org/downloads/)
[](LICENSE)
[](https://pypi.org/project/better-jupyter-mcp-server/)
[](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.ChengJiale150/jupyter-mcp-server)
[English](https://github.com/ChengJiale150/jupyter-mcp-server/blob/main/README_EN.md) | 中文
uvx 快速安装(推荐)
在安装uv后,直接配置MCP的JSON格式即可,示例如下:
```json
{
"mcpServers":{
"Jupyter-MCP-Server":{
"command": "uvx",
"args": [
"better-jupyter-mcp-server"
],
"env": {
"ALLOW_IMG": "true"
},
"transport": "stdio"
}
}
}
```
具体客户端集成详见[集成文档](https://github.com/ChengJiale150/jupyter-mcp-server/blob/main/docs/integration.md)
源代码
1. **克隆项目并安装依赖**
```bash
git clone https://github.com/ChengJiale150/jupyter-mcp-server
cd jupyter-mcp-server
uv sync
```
2. **(可选)配置config.toml**
进入[src/config.toml](./src/config.toml)文件,根据需要配置参数(如是否允许返回图片数据)
3. **启动Jupyter MCP Server**
```bash
uv run fastmcp run src/main.py
```
如果成功启动,会输出类似如下信息代表启动成功:
```bash
[09/14/25 20:14:59] INFO Starting MCP server 'Jupyter-MCP-Server' with transport 'stdio'
```
4. **配置标准JSON格式**
```json
{
"mcpServers":{
"Jupyter-MCP-Server":{
"command": "uv",
"args": [
"run",
"--directory",
"your/path/to/jupyter-mcp-server",
"src/main.py"
],
"env": {},
"transport": "stdio"
}
}
}
```
具体客户端集成详见[集成文档](https://github.com/ChengJiale150/jupyter-mcp-server/blob/main/docs/integration.md)
### 使用Jupyter MCP Server
本地手动启动Jupyter Server
在正式使用前,需要连接Jupyter Server,这里介绍如何在本地手动启动Jupyter Server:
1. **打开终端并激活环境**:
打开计算机终端命令行,并激活环境
对于使用conda(Anaconda)的用户,可以使用以下命令激活环境:
```bash
conda activate your_environment_name
```
这里为了方便起见,这里可以直接使用`base`环境(`conda activate base`)
然后切换到你当前的项目目录,方便后续的文件操作
```bash
cd your/path/to/your/project
```
2. **安装必要依赖**:
```bash
pip uninstall -y pycrdt datalayer_pycrdt
pip install jupyter nbformat datalayer_pycrdt jupyter-collaboration
```
3. **启动Jupyter Server**:
使用下述命令启动Jupyter Server
```bash
jupyter lab
```
成功启动后会弹出浏览器窗口,你可以在此查看根路径是否为工程目录
4. **获取认证Token**:
使用下述命令获取认证Token
```bash
jupyter server list
```
运行后会输出类似如下信息:
```bash
http://localhost:8888/?token=YOUR_TOKEN :: YOUR_PROJECT_PATH
```
其中`YOUR_TOKEN`为认证Token
5. **添加提示词与规则**
在正式使用前,你**必须**添加如下提示词于规则文件中以提供Jupyter MCP Server的必要连接信息:
```
以下是Jupyter服务器连接参数:
URL = http://localhost:8888
Token = YOUR_TOKEN
```
此外,推荐在提示词中添加关键Notebook路径信息,方便AI快速定位目标Notebook提高`connect_notebook`工具的执行效率,可以在Jupyter Lab网页中右键点击目标Notebook文件,选择`Copy Path`获取相对路径
在提供上述内容后,你就可以开始使用Jupyter MCP Server了!
使用LLM托管Jupyter Server
1. **安装必要依赖**:
```bash
pip uninstall -y pycrdt datalayer_pycrdt
pip install jupyter nbformat datalayer_pycrdt jupyter-collaboration
```
2. **提供提示词与规则文档**:
```markdown
## Jupyter MCP Server 使用指南
在正式使用Jupyter MCP Server前,你**必须**完成如下步骤:
1. **启动Jupyter Server**:
在当前项目目录中以不阻塞当前终端的方式在命令行终端中输入启动Jupyter Server,例如:
- `Window`: `start jupyter lab`
- `MacOS/Linux`: `nohup jupyter lab &`
2. **获取URL与认证Token**:
使用`jupyter server list`获取URL与认证Token
仅当完成上述步骤后,你才可以使用Jupyter MCP Server
```
## ✅ 最佳实践
- 使用支持多模态输入的大模型(如Gemini 2.5 Pro)进行交互,以充分利用最先进的多模态理解能力
- 使用支持MCP协议返回图像数据并支持解析的客户端(如Cursor、Gemini CLI等),部分客户端可能不支持该功能
- 将复杂任务(如数据科学建模)拆分为多个子任务(如数据清洗、特征工程、模型训练、模型评估等),并逐步执行
- 给出结构清晰的提示词与规则,这里可以参考[提示词与规则文档](https://github.com/ChengJiale150/jupyter-mcp-server/blob/main/docs/prompt_example.md)
- 在提示词中融入**专家经验与智慧**(如数据清洗、特征工程的技巧),这是AI最缺乏的,也是最需要补充的
- 尽可能提供丰富的上下文信息(如现有数据集的字段解释,文件路径,详细的任务要求等)
- 提供Few Shot案例,提供Baseline或已有Workflow作为参考
### 示例
- [Titanic数据集分析](https://github.com/ChengJiale150/jupyter-mcp-server/blob/main/example/Titanic)
## 🤝 贡献指南
我们欢迎社区贡献！如果您想为Jupyter MCP Server项目做出贡献，请：
1. Fork 本仓库
2. 创建您的特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交您的更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启一个 Pull Request
### 贡献类型
- 🐛 Bug修复
- 📝 旧功能完善
- ✨ 新功能开发
- 📚 文档改进
- 🌍 国际化支持
### 开发帮助文档
- 可以详见[项目架构文档](https://github.com/ChengJiale150/jupyter-mcp-server/blob/main/src/README.md)辅助理解项目架构与关键通信流程
## 🤗 致谢
本项目受到以下项目的帮助,在此表示感谢:
- [DataLayer](https://github.com/datalayer): 感谢DataLayer开源的[jupyter_nbmodel_client](https://github.com/datalayer/jupyter-nbmodel-client)与[jupyter_kernel_client](https://github.com/datalayer/jupyter-kernel-client)库,为Jupyter MCP的快速开发提供了极大的帮助
- [FastMCP](https://github.com/jlowin/fastmcp): 感谢FastMCP的开发者们,没有FastMCP就没有Jupyter MCP的快速集成
此外,本项目还参考了以下已有Jupyter MCP服务的实现,在此也一并表示感谢:
- [datalayer/jupyter-mcp-server](https://github.com/datalayer/jupyter-mcp-server)
- [jjsantos01/jupyter-notebook-mcp](https://github.com/jjsantos01/jupyter-notebook-mcp)
- [ihrpr/mcp-server-jupyter](https://github.com/ihrpr/mcp-server-jupyter)
- [itisaevalex/jupyter-mcp-extended](https://github.com/itisaevalex/jupyter-mcp-extended)
---
**如果这个项目对您有帮助，请给我们一个 ⭐️**
Made with ❤️ by [ChengJiale150](https://github.com/ChengJiale150)