Jupyter MCP服务器

一个全面的模型上下文协议(MCP)服务器,连接AI代理与Jupyter笔记本,实现实时代码执行、可视化生成和高级图像提取功能。

  • by JosephLin11
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 josephlin11/jupyter-mcp-server

使用说明

🚀 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客户端

安装

  1. 克隆存储库

    git clone https://github.com/JosephLin11/jupyter-mcp-server.git
    cd jupyter-mcp-server
    
  2. 安装依赖项

    pip install -r requirements.txt
    
  3. 启动Jupyter服务器

    ./scripts/start_jupyter.sh
    
  4. 配置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

🤝 贡献

欢迎投稿!请按照以下步骤操作:

  1. 分叉存储库
  2. 创建要素分支(git checkout -b feature/amazing-feature)
  3. 提交您的更改(git commit -m 'Add amazing feature')
  4. 推到分支(git push origin feature/amazing-feature)
  5. 打开拉取请求

📄 许可证

此项目根据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增强和维护