使用说明
🚀 Jupyter MCP服务器
一个全面的模型上下文协议(MCP)服务器,将AI代理与Jupyter笔记本连接起来,实现实时代码执行、可视化生成和高级图像提取功能。
🎯 关于本项目
该项目是由开发人员开发的原始Jupyter MCP服务器的分支和增强 股份有限公司数据层。特别感谢Datalayer团队在将Jupyter与模型上下文协议生态系统集成方面所做的基础工作。
此分叉中的主要增强功能:
- 改进了文档和设置过程
- 增强的错误处理和鲁棒性
- 其他示例配置
- 简化安装和配置
- 更新了依赖关系和兼容性
🌟 主要特点
🎯 实时Jupyter集成
- 实时代码执行:通过WebSocket连接实时执行Python代码
- 内核管理:自动创建内核、生命周期管理和清理
- 会话保持:在多个操作中保持状态
🖼️ 高级图像提取
- 多格式支持:从matplotlib、seaborn、plotly中提取PNG和JPEG图像
- Base64编码:可用于AI处理的现成图像数据
- 综合输出处理:文本、图像、错误和执行结果
📚 完整的笔记本管理
- 文件操作:创建、删除、在多个笔记本之间切换
- 细胞操作:使用完整的CRUD操作添加、修改、移动、删除单元格
- 内容管理:同时支持markdown和代码单元格
🛡️ 企业就绪安全
- 智能XSRF处理:自动令牌检测和管理
- 身份验证支持:与标记化的Jupyter服务器兼容
- 错误恢复:连接问题的巧妙回退
🏗️ 建筑
graph TD
A[AI Agent/Claude] --> B[MCP Server]
B --> C[Jupyter Server API]
B --> D[WebSocket Channels]
C --> E[Kernel Management]
D --> F[Real-time Execution]
F --> G[Output Capture]
G --> H[Image Extraction]
G --> I[Text Processing]
B --> J[Notebook Files]
🛠️ 18个综合工具
📝 单元内容管理
add_execute_code_cell-执行具有实时输出的Python代码add_markdown_cell-添加格式化文档modify_cell-编辑现有单元格内容change_cell_type-在markdown和代码单元格之间转换
🖼️ 输出提取
get_cell_image_output-提取base64编码的图像(PNG/JPEG)get_cell_text_output-获取所有文本输出,包括错误和回溯
🗂️ 笔记本文件操作
create_notebook-创建新的笔记本文件delete_notebook-安全删除笔记本文件switch_notebook-更改活动笔记本list_notebooks-浏览可用笔记本
🔍 数据发现
list_cells-所有带有预览的单元格概览read_cell-特定细胞的全部内容get_notebook_info-全面的笔记本元数据
🚀 快速开始
先决条件
- Python 3.11+
- Jupyter笔记本
- Claude Desktop或兼容的MCP客户端
安装
-
克隆存储库
git clone https://github.com/JosephLin11/jupyter-mcp-server.git cd jupyter-mcp-server -
安装依赖项
pip install -r requirements.txt -
启动Jupyter服务器
./scripts/start_jupyter.sh -
配置Claude桌面 添加到您的
claude_desktop_config.json:{ "mcpServers": { "jupyter": { "command": "python", "args": ["/path/to/your/jupyter-mcp-server/src/jupyter_mcp_server.py"] } } }💡 小贴士:运行
python3 scripts/get_claude_config.py使用当前路径生成正确的配置!
💡 示例用例
📊 数据可视化管道
# 1. Create and execute visualization code
add_execute_code_cell(cell_content="""
import matplotlib.pyplot as plt
import numpy as np
import seaborn as sns
# Generate sample data
data = np.random.normal(0, 1, 1000)
# Create beautiful visualization
plt.figure(figsize=(12, 8))
plt.subplot(2, 2, 1)
plt.hist(data, bins=50, alpha=0.7, color='skyblue')
plt.title('Distribution Analysis')
plt.subplot(2, 2, 2)
sns.boxplot(y=data)
plt.title('Box Plot Analysis')
plt.tight_layout()
plt.show()
""")
# 2. Extract the generated image
get_cell_image_output(cell_index=0)
🧪 科学计算
# 3D surface visualization
add_execute_code_cell(cell_content="""
from mpl_toolkits.mplot3d import Axes3D
import numpy as np
import matplotlib.pyplot as plt
fig = plt.figure(figsize=(12, 9))
ax = fig.add_subplot(111, projection='3d')
# Create mesh
x = np.linspace(-5, 5, 100)
y = np.linspace(-5, 5, 100)
X, Y = np.meshgrid(x, y)
Z = np.sin(np.sqrt(X**2 + Y**2))
# Render surface
surface = ax.plot_surface(X, Y, Z, cmap='plasma', alpha=0.9)
ax.set_title('3D Mathematical Function')
plt.colorbar(surface)
plt.show()
""")
# Extract 3D visualization
get_cell_image_output(cell_index=1)
🏆 技术亮点
高级WebSocket实现
- 与Jupyter内核的实时双向通信
- 全面的消息类型处理(execute_result、display_data、stream、error)
- 自动重新连接和回退机制
智能输出处理
- 采用base64编码的多格式图像提取(PNG、JPEG)
- 结构化输出捕获保留元数据
- 具有完全回溯支持的错误处理
稳健的安全模型
- XSRF令牌自动检测和管理
- 支持多个身份验证端点
- 不同Jupyter配置的优雅降级
企业级错误处理
- 具有可配置级别的全面日志记录
- 可靠性回退执行模式
- 资源清理和连接管理
📊 与备选方案的比较
| 功能 | 此实现 | jjsantos01 MCP | 光标MCP |
|---|---|---|---|
| 可用工具 | 🏆 18工具 | 10个工具 | 8-10个工具 |
| 图像提取 | 🏆 PNG+JPEG | 仅PNG | 无 |
| 设置复杂性 | 🏆 自动 | 手动浏览器初始化 | CLI参数 |
| 版本支持 | 🏆 所有Jupyter版本 | 仅限Jupyter 6.x | 版本无关 |
| 实时执行 | 🏆 WebSocket+HTTP | WebSocket网桥 | 仅限文件 |
| 安全处理 | 🏆 自动XSRF | 基本 | 增强 |
🧪 测试
运行综合测试套件:
# Test image extraction capabilities
python tests/test_image_extraction.py
# Test notebook operations
python tests/test_notebook_save.py
📁 项目结构
jupyter-mcp-server/
├── src/
│ └── jupyter_mcp_server.py # Main MCP server implementation
├── notebooks/ # 📓 All Jupyter notebooks are created here
│ └── mcp_notebook.ipynb # Default notebook for MCP operations
├── tests/
│ ├── test_image_extraction.py # Image extraction tests
│ └── test_notebook_save.py # Notebook operation tests
├── scripts/
│ ├── start_jupyter.sh # Jupyter server startup script
│ └── get_claude_config.py # Claude configuration generator
├── examples/
│ ├── claude_desktop_config.json # Example configuration
│ ├── mcp_notebook.ipynb # Example notebook
│ └── new_notebook.ipynb # Sample notebook
├── docs/
│ ├── MCP_TOOLS_SUMMARY.md # Complete tool reference
│ ├── SETUP.md # Setup guide
│ └── IMAGE_EXTRACTION_README.md # Image extraction guide
├── requirements.txt # Python dependencies
├── pyproject.toml # Project configuration
└── README.md # Project documentation
🤝 贡献
欢迎投稿!请按照以下步骤操作:
- 分叉存储库
- 创建要素分支(
git checkout -b feature/amazing-feature) - 提交您的更改(
git commit -m 'Add amazing feature') - 推到分支(
git push origin feature/amazing-feature) - 打开拉取请求
📄 许可证
此项目根据BSD 3条款许可证获得许可-请参阅 许可证 文件以获取详细信息。
🌟 致谢
- 原创发展: 股份有限公司数据层。 用于创建基础Jupyter MCP服务器
- 受模型上下文协议生态系统的启发
- 基于强大的Jupyter服务器API
- 通过各种MCP实现的想法进行了增强
- 特别感谢开源社区
📧 联系
林以信 - GitHub
项目链接: https://github.com/JosephLin11/jupyter-mcp-server
原始项目: https://github.com/datalayer/jupyter-mcp-server
⭐ 如果你觉得这个存储库有用,请为其加星! ⭐
内置于❤️ 面向人工智能和数据科学界
最初由Datalayer开发,由Joseph Lin增强和维护
