🚀 Jupyter MCP Server

🚀 Jupyter MCP Server

一个全面的模型上下文协议（MCP）服务，可连接 AI Agent 与 Jupyter 笔记本，支持实时代码执行、可视化生成和高级图像提取功能。

🎯 关于本项目

本项目是由 Datalayer, Inc. 开发的原版 Jupyter MCP Server 的分支和增强版本。特别感谢 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 Notebook
• Claude Desktop 或兼容的 MCP 客户端

安装

1. 克隆代码库

   git clone https://github.com/JosephLin11/jupyter-mcp-server.git
   cd jupyter-mcp-server
   

2. 安装依赖项

   pip install -r requirements.txt
   

3. 启动 Jupyter Server

   ./scripts/start_jupyter.sh
   

4. 配置 Claude Desktop 添加到你的 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）
• 自动重新连接和回退机制

智能输出处理

• 提取多种格式的图像（PNG、JPEG），并进行 base64 编码
• 结构化捕获输出，同时保留元数据
• 错误处理支持完整回溯信息

稳健的安全模型

• 自动检测和管理 XSRF 令牌
• 支持多个身份验证端点
• 针对不同 Jupyter 配置进行平稳降级

企业级错误处理

• 提供可配置日志级别的全面日志记录
• 提供可靠的回退执行模式
• 资源清理和连接管理

📊 与替代方案对比

功能	此实现	jjsantos01 MCP	Cursor 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

🤝 贡献

欢迎贡献！请按照以下步骤操作：

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 发起 Pull Request

📄 许可证

本项目采用 BSD 3-Clause 许可证授权，详情请参阅 LICENSE 文件。

🌟 致谢

• 原始开发：Datalayer, Inc.，感谢其创建了 Jupyter MCP Server 的基础版本
• 灵感来自 Model Context Protocol 生态系统
• 基于稳健的 Jupyter Server API 构建
• 融入了各种 MCP 实现中的创意并加以改进
• 特别感谢开源社区

📧 联系方式

Joseph Lin - GitHub

项目链接：https://github.com/JosephLin11/jupyter-mcp-server

原始项目：https://github.com/datalayer/jupyter-mcp-server

---