Jupythunder

한국어 설명

Jupythunder

Jupythunder 是一个用于连接 LLM 聊天界面（Claude）与 Jupyter Notebook 的中间件。该项目让用户能够以更接近自然语言的方式与 Jupyter Notebook 交互。

主要功能

• 自然语言代码转换：LLM 将用户以自然语言风格编写的代码转换为正确的 Python 代码
• Jupyter 远程连接：支持通过用户提供的 Jupyter Notebook URL（含 token）进行远程连接
• 代码执行：在 Jupyter Notebook 中执行转换后的代码并返回结果
• 代码问答：通过 /question 命令查询已定义函数、变量等信息
• 状态管理：管理连接状态和会话信息
• Notebook 文件管理：支持创建、打开、管理单元格以及保存 .ipynb 文件
• 自然语言数据分析：通过自然语言请求完成数据分析和可视化工作流
• 单元格查询与执行：查看特定单元格内容、执行特定单元格、按顺序执行所有单元格

安装

前置条件

• Python 3.10 或更高版本
• Jupyter Notebook
• Claude for Desktop（或其他 MCP 客户端）

安装步骤

1. 克隆仓库：

   git clone https://github.com/username/jupythunder.git
   cd jupythunder
   

2. 安装依赖：

   pip install -r requirements.txt
   

使用方法

1. 运行 Jupyter Notebook 服务端

在单独的终端中运行 Jupyter Notebook 服务端：

jupyter notebook

检查日志中的 URL 和 token（例如，http://localhost:8888/?token=abcdef1234567890）。

2. 运行 MCP 服务

python jupythunder_server.py

3. 配置 Claude for Desktop

将 MCP 服务添加到 Claude for Desktop 的 claude_desktop_config.json 文件中：

{
  "mcpServers": {
    "jupythunder": {
      "command": "/absolute/path/python",
      "args": ["/absolute/path/jupythunder_server.py"]
    }
  }
}

重要：必须使用 Python 和脚本文件的绝对路径。

4. 重启 Claude for Desktop

更改配置后，重启 Claude for Desktop。

5. 使用示例

1. 连接到 Jupyter：

   Connect to Jupyter Notebook. URL is http://localhost:8888/tree?token=abcdef1234567890
   

2. 创建新 Notebook：

   /notebook:data_analysis_notebook
   

3. 打开现有 Notebook：

   /open:data_analysis_notebook
   

4. 自然语言数据分析请求：

   Generate random data
   

5. 数据分析与可视化：

   Show statistical analysis results for the generated data
   
   Visualize the correlation between age and income on a graph
   

6. 编写并执行代码：

   def calculate_savings(income, expense):
       return income - expense
       
   df['savings'] = calculate_savings(df['income'], df['expenses'])
   df.head()
   

7. 查询函数信息：

   /question: What functions are currently defined?
   

8. 查询 Notebook 内容：

   What is the current notebook content?
   

9. 查询并执行特定单元格：

   Show the content of the first cell
   Execute the second cell
   

10. 执行所有单元格：

    按顺序执行 Notebook 中的所有单元格
    

功能详细说明

Notebook 管理功能

• 创建新 Notebook：使用 /notebook:notebook_name 命令创建新 Notebook
• 打开现有 Notebook：使用 /open:notebook_name 命令打开现有 Notebook
• 查看 Notebook 内容：检查当前 Notebook 的单元格组成

单元格管理功能

• 查看单元格内容：检查特定单元格中的代码或 Markdown 内容
• 执行特定单元格：选择性地执行所需单元格
• 执行所有单元格：按顺序执行 Notebook 中的所有单元格
• 添加 Markdown 单元格：自动将自然语言说明添加为 Markdown 单元格
• 添加代码单元格：将转换后的 Python 代码添加为代码单元格
• 保存执行结果：代码执行结果会自动保存到 Notebook 中

自然语言数据分析功能

• 数据生成：通过“生成随机数据”等自然语言请求生成测试数据
• 统计分析：通过“显示数据的汇总统计信息”等请求执行数据分析
• 数据可视化：通过“绘制年龄分布图”等自然语言请求进行可视化
• 相关性分析：通过“分析变量之间的相关性”等请求分析变量关系

命令列表

命令	描述	示例
/notebook:name	创建新笔记本	/notebook:data_analysis
/open:name	打开现有笔记本	/open:test
/question:content	代码相关问题	/question:function list
/help	显示帮助	/help

故障排查

无法连接到 MCP 服务 jupythunder：spawn pythonENOENT

当找不到 Python 可执行文件时，会出现此错误。可通过以下方法解决：

1. 使用 Python 绝对路径：

   {
     "mcpServers": {
       "jupythunder": {
         "command": "/absolute/path/python",
         "args": ["/absolute/path/jupythunder_server.py"]
       }
     }
   }
   

   可以使用以下命令查找 Python 绝对路径：

   which python  # macOS/Linux
   where python  # Windows
   

2. 使用 python3 命令：

   {
     "mcpServers": {
       "jupythunder": {
         "command": "python3",
         "args": ["/absolute/path/jupythunder_server.py"]
       }
     }
   }
   

Jupyter 连接失败

• 检查 Jupyter 服务是否正在运行
• 确认提供的 URL 和令牌是否正确
• 检查防火墙设置

创建或打开笔记本失败

• 检查是否有 Jupyter 服务的写入权限
• 确保笔记本名称不包含特殊字符
• 检查是否已存在同名笔记本

单元格执行问题

• 检查代码是否存在语法错误
• 确认必要的变量或函数已在前面的单元格中定义
• 如果笔记本中没有显示执行结果，请重启服务

项目结构

jupythunder/
├── jupythunder_server.py  # Main server implementation
├── jupythunder_client.py  # Jupyter API client
├── tools.py               # MCP tool implement
├── utils.py               # Utility functions
└── requirements.txt       # Project dependencies

核心组件

• FastMCP Server：MCP 协议处理
• JupyterClient Class：Jupyter API 交互和笔记本管理
• 工具：用于连接、执行、查询和笔记本管理的工具
• 命令处理：特殊命令解析
• 状态管理：生命周期上下文管理
• 自然语言处理：将自然语言请求转换为 Python 代码
• 单元格管理：用于查看单元格内容、执行单元格和保存结果的函数

未来改进

1. 大模型集成：使用实际的大模型增强自然语言转换能力
2. 数据可视化扩展：支持多种可视化类型
3. 笔记本模板：提供适用于数据分析、机器学习等场景的模板
4. 文件上传：支持上传数据文件并自动分析
5. 协作功能：支持多用户和共享功能
6. 交互式小组件：增强对 Jupyter 小组件的支持
7. GPU 加速：为深度学习任务提供 GPU 加速支持

依赖项

• mcp[cli] >= 1.5.0：MCP 协议实现
• requests >= 2.31.0：HTTP 请求处理
• websocket-client >= 1.6.0：WebSocket 通信
• python-dotenv >= 1.0.0：环境变量管理
• urllib3 >= 2.0.0：HTTP 客户端

许可证

MIT 许可证

---

Jupythunder（한국어）

Jupythunder 是连接 LLM 聊天界面（Claude）与 Jupyter Notebook 的中间件。借助此项目，用户可以通过接近自然语言的方式与 Jupyter Notebook 交互。

主要功能

• 自然语言代码转换：将用户以接近自然语言的方式编写的代码转换为正确的 Python 代码
• Jupyter 远程连接：通过用户提供的 Jupyter Notebook URL（包含令牌）支持远程连接
• 代码执行：在 Jupyter Notebook 中执行转换后的代码并返回结果
• 代码提问：通过 /question 命令查询已定义函数、变量等信息
• 状态管理：管理连接状态和会话信息
• 笔记本文件管理：支持创建、打开 .ipynb 文件、管理单元格及保存
• 自然语言数据分析：通过自然语言请求执行数据分析和可视化工作流
• 单元格查看与执行：支持查看指定单元格内容、执行指定单元格以及按顺序执行所有单元格

安装方法

前置要求

• Python 3.10 或更高版本
• Jupyter Notebook
• Claude for Desktop（或其他 MCP 客户端）

安装步骤

1. 克隆存储库：

   git clone https://github.com/username/jupythunder.git
   cd jupythunder
   

2. 安装依赖项：

   pip install -r requirements.txt
   

使用方法

1. 启动 Jupyter Notebook 服务

在单独的终端中启动 Jupyter Notebook 服务：

jupyter notebook

请在日志中确认 URL 和令牌（例如：http://localhost:8888/?token=abcdef1234567890）。

2. 启动 MCP 服务

python jupythunder_server.py

3. 配置 Claude for Desktop

在 Claude for Desktop 的 claude_desktop_config.json 文件中添加 MCP 服务：

{
  "mcpServers": {
    "jupythunder": {
      "command": "/절대/경로/python",
      "args": ["/절대/경로/jupythunder_server.py"]
    }
  }
}

重要：必须使用 Python 和脚本文件的绝对路径。

4. 重启 Claude for Desktop

更改设置后，重启 Claude for Desktop。

5. 使用示例

1. 连接到 Jupyter：

   Jupyter Notebook에 연결해줘. URL은 http://localhost:8888/tree?token=abcdef1234567890
   

2. 创建新笔记本：

   /notebook:데이터분석_노트북
   

3. 打开现有笔记本：

   /open:데이터분석_노트북
   

4. 用自然语言请求数据分析：

   랜덤 데이터를 생성해줘
   

5. 数据分析与可视化：

   생성된 데이터에 대한 통계 분석 결과를 보여줘
   
   나이와 수입의 상관관계를 그래프로 시각화해줘
   

6. 编写并运行代码：

   def calculate_savings(income, expense):
       return income - expense
       
   df['저축액'] = calculate_savings(df['수입'], df['지출'])
   df.head()
   

7. 查询函数信息：

   /question: 지금 정의된 함수가 뭐가 있지?
   

8. 查询笔记本内容：

   현재 노트북의 내용이 어떻게 되어 있어?
   

9. 查询并运行特定单元格：

   첫번째 셀의 내용을 보여줘
   두번째 셀을 실행해줘
   

10. 运行所有单元格：

    请依次运行笔记本中的所有单元格
    

主要功能详解

笔记本管理功能

• 创建新笔记本：使用 /notebook:笔记本名称 命令创建新笔记本。
• 打开现有笔记本：使用 /open:笔记本名称 命令打开现有笔记本。
• 查询笔记本内容：查看当前正在处理的笔记本中的单元格结构。

单元格管理功能

• 查询单元格内容：查看特定单元格中的代码或 Markdown 内容。
• 运行特定单元格：可以只运行选定的单元格。
• 运行所有单元格：可以依次运行笔记本中的所有单元格。
• 添加 Markdown 单元格：自然语言说明会自动添加为 Markdown 单元格。
• 添加代码单元格：转换后的 Python 代码会添加为代码单元格。
• 保存运行结果：代码运行结果会自动保存到笔记本中。

自然语言数据分析功能

• 生成数据：通过“生成随机数据”等自然语言请求生成测试数据。
• 统计分析：通过“显示数据汇总统计信息”等请求执行数据分析。
• 数据可视化：通过“绘制年龄分布图”等自然语言请求创建可视化图表。
• 相关性分析：通过“分析变量之间的相关性”等请求分析变量关系。

命令列表

命令	说明	示例
/notebook:이름	创建新笔记本	/notebook:데이터분석
/open:이름	打开现有笔记本	/open:test
/question:내용	提出与代码相关的问题	/question:함수 목록
/help	显示帮助信息	/help

问题排查

无法连接到 MCP 服务 jupythunder：spawn pythonENOENT

找不到 Python 可执行文件时会出现此错误。请通过以下方式解决：

1. 使用 Python 绝对路径：

   {
     "mcpServers": {
       "jupythunder": {
         "command": "/절대/경로/python",
         "args": ["/절대/경로/jupythunder_server.py"]
       }
     }
   }
   

   可以通过以下命令确认 Python 绝对路径：

   which python  # macOS/Linux
   where python  # Windows
   

2. 使用 python3 命令：

   {
     "mcpServers": {
       "jupythunder": {
         "command": "python3",
         "args": ["/절대/경로/jupythunder_server.py"]
       }
     }
   }
   

Jupyter 连接失败

• 确认 Jupyter 服务正在运行
• 确认提供的 URL 和令牌正确无误
• 检查防火墙设置

创建或打开笔记本失败

• 确认 Jupyter 服务具有写入权限
• 确认笔记本名称不包含特殊字符
• 确认不存在同名笔记本

单元格运行问题

• 确认代码没有语法错误
• 确认所需变量或函数已在之前的单元格中定义
• 如果运行结果未显示在笔记本中，请尝试重启服务

项目结构

jupythunder/
├── jupythunder_server.py  # 메인 서버 구현
├── jupythunder_client.py  # Jupyter API 클라이언트 
├── tools.py               # MCP 도구 구현
├── utils.py               # 유틸리티 함수
└── requirements.txt       # 프로젝트 의존성

主要组成部分

• FastMCP 服务：处理 MCP 协议
• JupyterClient 类：与 Jupyter API 交互并管理笔记本
• 工具：用于连接、运行、查询和管理笔记本
• 命令处理：解析特殊命令语法
• 状态管理：管理生命周期上下文
• 自然语言处理：将自然语言请求转换为 Python 代码
• 单元格管理：查询单元格内容、运行单元格并保存结果

后续改进

1. 集成 LLM：强化使用实际 LLM 进行自然语言转换的功能
2. 扩展数据可视化：支持多种可视化类型
3. 笔记本模板：提供用于数据分析、机器学习等不同用途的模板
4. 文件上传：支持上传数据文件并自动分析
5. 协作功能：支持多用户和共享
6. 交互式小组件：强化对 Jupyter 小组件的支持
7. GPU 加速：支持用于深度学习任务的 GPU 加速

依赖项

• mcp[cli] >= 1.5.0：实现 MCP 协议
• requests >= 2.31.0：处理 HTTP 请求
• websocket-client >= 1.6.0：WebSocket 通信
• python-dotenv >= 1.0.0：管理环境变量
• urllib3 >= 2.0.0：HTTP 客户端

许可证

MIT 许可证