![jupyhunder(jolteon)](https://i.namu.wiki/i/WJMrzZfHKfP2FWaZMt9erPoeY2PnI-iH5ypYAn3TM6ZU08cK46hYp_1PHi0YtKGmtwwwwajJzn6J-p7RHZ4kXORbkcHEpeVvm_z_EYfM31TuP9bLJy9AMhtsHtg4sabcHUpCNv3Q3c_GPLoGmm1Yuw.webp)

[한국어 설명](https://github.com/kbsooo/jupythunder#jupythunder-%ED%95%9C%EA%B5%AD%EC%96%B4)

# Jupythunder

Jupythunder is a middleware that connects the LLM chat interface (Claude) with Jupyter Notebook. This project allows users to interact with Jupyter Notebook in a way that's closer to natural language.

## Key Features

- **Natural Language Code Conversion**: LLM converts code written by users in a natural language style into correct Python code
- **Jupyter Remote Connection**: Supports remote connections via user-provided Jupyter Notebook URL (with token)
- **Code Execution**: Executes converted code in Jupyter Notebook and returns results
- **Code Questions**: Query information about defined functions, variables, etc. via the `/question` command
- **State Management**: Manages connection state and session information
- **Notebook File Management**: Supports creating, opening, cell management and saving .ipynb files
- **Natural Language Data Analysis**: Data analysis and visualization workflow through natural language requests
- **Cell Query and Execution**: View specific cell contents, execute specific cells, execute all cells sequentially

## Installation

### Prerequisites

- Python 3.10 or higher
- Jupyter Notebook
- Claude for Desktop (or another MCP client)

### Installation Steps

1. Clone the repository:
   ```bash
   git clone https://github.com/username/jupythunder.git
   cd jupythunder
   ```

2. Install dependencies:
   ```bash
   pip install -r requirements.txt
   ```

## Usage

### 1. Run Jupyter Notebook Server

Run the Jupyter Notebook server in a separate terminal:
```bash
jupyter notebook
```
Check the logs for the URL and token (e.g., `http://localhost:8888/?token=abcdef1234567890`).

### 2. Run MCP Server

```bash
python jupythunder_server.py
```

### 3. Configure Claude for Desktop

Add the MCP server to the `claude_desktop_config.json` file of Claude for Desktop:

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

**Important**: You must use the **absolute path** of Python and the script file.

### 4. Restart Claude for Desktop

Restart Claude for Desktop after changing the configuration.

### 5. Usage Examples

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

2. **Create New Notebook**:
   ```
   /notebook:data_analysis_notebook
   ```

3. **Open Existing Notebook**:
   ```
   /open:data_analysis_notebook
   ```

4. **Natural Language Data Analysis Request**:
   ```
   Generate random data
   ```
   
5. **Data Analysis and Visualization**:
   ```
   Show statistical analysis results for the generated data
   
   Visualize the correlation between age and income on a graph
   ```

6. **Writing and Executing Code**:
   ```
   def calculate_savings(income, expense):
       return income - expense
       
   df['savings'] = calculate_savings(df['income'], df['expenses'])
   df.head()
   ```

7. **Function Information Lookup**:
   ```
   /question: What functions are currently defined?
   ```

8. **Notebook Content Lookup**:
   ```
   What is the current notebook content?
   ```

9. **Specific Cell Lookup and Execution**:
   ```
   Show the content of the first cell
   Execute the second cell
   ```

10. **Execute All Cells**:
    ```
    Execute all cells in the notebook sequentially
    ```

## Detailed Feature Description

### Notebook Management Features

* **Create New Notebook**: Create a new notebook with the `/notebook:notebook_name` command
* **Open Existing Notebook**: Open an existing notebook with the `/open:notebook_name` command
* **View Notebook Content**: Check the cell composition of the current notebook

### Cell Management Features

* **View Cell Content**: Check the code or markdown content of specific cells
* **Execute Specific Cell**: Selectively execute desired cells
* **Execute All Cells**: Execute all cells in the notebook sequentially
* **Add Markdown Cell**: Natural language explanations are automatically added as markdown cells
* **Add Code Cell**: Converted Python code is added as code cells
* **Save Execution Results**: Code execution results are automatically saved in the notebook

### Natural Language Data Analysis Features

* **Data Generation**: Generate test data with natural language requests like "Generate random data"
* **Statistical Analysis**: Perform data analysis with requests like "Show summary statistics for the data"
* **Data Visualization**: Visualize with natural language requests like "Draw a graph of the age distribution"
* **Correlation Analysis**: Analyze relationships with requests like "Analyze the correlation between variables"

## Command List

| Command | Description | Example |
|--------|------|------|
| `/notebook:name` | Create new notebook | `/notebook:data_analysis` |
| `/open:name` | Open existing notebook | `/open:test` |
| `/question:content` | Code-related question | `/question:function list` |
| `/help` | Display help | `/help` |

## Troubleshooting

### could not connect to MCP server jupythunder: spawn pythonENOENT

This error occurs when the Python executable file cannot be found. Resolve it with these methods:

1. **Use Python Absolute Path**:
   ```json
   {
     "mcpServers": {
       "jupythunder": {
         "command": "/absolute/path/python",
         "args": ["/absolute/path/jupythunder_server.py"]
       }
     }
   }
   ```
   
   You can find the Python absolute path with these commands:
   ```bash
   which python  # macOS/Linux
   where python  # Windows
   ```

2. **Use python3 Command**:
   ```json
   {
     "mcpServers": {
       "jupythunder": {
         "command": "python3",
         "args": ["/absolute/path/jupythunder_server.py"]
       }
     }
   }
   ```

### Jupyter Connection Failure

- Check if the Jupyter server is running
- Verify that the provided URL and token are correct
- Check firewall settings

### Notebook Creation or Opening Failure

- Check if you have write permissions to the Jupyter server
- Make sure the notebook name does not contain special characters
- Check if a notebook with the same name already exists

### Cell Execution Issues

- Check for syntax errors in the code
- Verify that necessary variables or functions are defined in previous cells
- Restart the server if execution results are not displayed in the notebook

## Project Structure

```
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
```

### Key Components

- **FastMCP Server**: MCP protocol handling
- **JupyterClient Class**: Jupyter API interaction and notebook management
- **Tools**: Tools for connection, execution, query, and notebook management
- **Command Handling**: Special command parsing
- **State Management**: Lifespan context management
- **Natural Language Processing**: Converting natural language requests to Python code
- **Cell Management**: Functions for viewing cell content, execution, and saving results

## Future Improvements

1. **LLM Integration**: Enhance natural language conversion capabilities using actual LLMs
2. **Data Visualization Extensions**: Support for various visualization types
3. **Notebook Templates**: Provide purpose-specific templates for data analysis, machine learning, etc.
4. **File Upload**: Support for data file upload and automatic analysis
5. **Collaboration Features**: Multi-user support and sharing features
6. **Interactive Widgets**: Enhanced support for Jupyter widgets
7. **GPU Acceleration**: GPU acceleration support for deep learning tasks

## Dependencies

- mcp[cli] >= 1.5.0: MCP protocol implementation
- requests >= 2.31.0: HTTP request handling
- websocket-client >= 1.6.0: WebSocket communication
- python-dotenv >= 1.0.0: Environment variable management
- urllib3 >= 2.0.0: HTTP client

## License

MIT License

---

# Jupythunder (한국어)

Jupythunder는 LLM 채팅 인터페이스(Claude)와 Jupyter Notebook을 연결해주는 미들웨어입니다. 이 프로젝트를 통해 사용자는 자연어에 가까운 방식으로 Jupyter Notebook과 상호작용할 수 있습니다.

## 주요 기능

- **자연어 코드 변환**: 사용자가 자연어에 가까운 방식으로 작성한 코드를 LLM이 올바른 Python 코드로 변환
- **Jupyter 원격 연결**: 사용자가 제공한 Jupyter Notebook URL(토큰 포함)을 통해 원격 연결 지원
- **코드 실행**: 변환된 코드를 Jupyter Notebook에서 실행하고 결과 반환
- **코드 질문**: `/question` 명령어를 통해 정의된 함수, 변수 등의 정보 조회
- **상태 관리**: 연결 상태 및 세션 정보 관리
- **노트북 파일 관리**: .ipynb 파일 생성, 열기, 셀 관리 및 저장 기능 지원
- **자연어 데이터 분석**: 자연어 요청을 통한 데이터 분석 및 시각화 워크플로우
- **셀 조회 및 실행**: 특정 셀 내용 조회, 특정 셀 실행, 모든 셀 순차 실행 지원

## 설치 방법

### 사전 요구사항

- Python 3.10 이상
- Jupyter Notebook
- Claude for Desktop (또는 다른 MCP 클라이언트)

### 설치 단계

1. 저장소 복제:
   ```bash
   git clone https://github.com/username/jupythunder.git
   cd jupythunder
   ```

2. 의존성 설치:
   ```bash
   pip install -r requirements.txt
   ```

## 사용 방법

### 1. Jupyter Notebook 서버 실행

별도의 터미널에서 Jupyter Notebook 서버를 실행합니다:
```bash
jupyter notebook
```
로그에서 URL과 토큰을 확인하세요 (예: `http://localhost:8888/?token=abcdef1234567890`).

### 2. MCP 서버 실행

```bash
python jupythunder_server.py
```

### 3. Claude for Desktop 설정

Claude for Desktop의 `claude_desktop_config.json` 파일에 MCP 서버를 추가합니다:

```json
{
  "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:노트북이름` 명령어로 기존 노트북을 엽니다.
* **노트북 내용 조회**: 현재 작업 중인 노트북의 셀 구성을 확인할 수 있습니다.

### 셀 관리 기능

* **셀 내용 조회**: 특정 셀의 코드나 마크다운 내용을 확인할 수 있습니다.
* **특정 셀 실행**: 원하는 셀만 선택적으로 실행할 수 있습니다.
* **모든 셀 실행**: 노트북의 모든 셀을 순차적으로 실행할 수 있습니다.
* **마크다운 셀 추가**: 자연어 설명이 마크다운 셀로 자동 추가됩니다.
* **코드 셀 추가**: 변환된 Python 코드가 코드 셀로 추가됩니다.
* **실행 결과 저장**: 코드 실행 결과가 노트북에 자동으로 저장됩니다.

### 자연어 데이터 분석 기능

* **데이터 생성**: "랜덤 데이터 생성" 같은 자연어 요청으로 테스트 데이터를 생성합니다.
* **통계 분석**: "데이터 요약 통계 보여줘" 등의 요청으로 데이터 분석을 수행합니다.
* **데이터 시각화**: "나이 분포를 그래프로 그려줘"처럼 자연어 요청으로 시각화합니다.
* **상관관계 분석**: "변수 간 상관관계 분석해줘"와 같은 요청으로 관계를 분석합니다.

## 명령어 목록

| 명령어 | 설명 | 예시 |
|--------|------|------|
| `/notebook:이름` | 새 노트북 생성 | `/notebook:데이터분석` |
| `/open:이름` | 기존 노트북 열기 | `/open:test` |
| `/question:내용` | 코드 관련 질문 | `/question:함수 목록` |
| `/help` | 도움말 표시 | `/help` |

## 문제 해결

### could not connect to MCP server jupythunder: spawn pythonENOENT

이 오류는 Python 실행 파일을 찾지 못할 때 발생합니다. 다음 방법으로 해결하세요:

1. **Python 절대 경로 사용**:
   ```json
   {
     "mcpServers": {
       "jupythunder": {
         "command": "/절대/경로/python",
         "args": ["/절대/경로/jupythunder_server.py"]
       }
     }
   }
   ```
   
   Python 절대 경로는 다음 명령어로 확인할 수 있습니다:
   ```bash
   which python  # macOS/Linux
   where python  # Windows
   ```

2. **python3 명령어 사용**:
   ```json
   {
     "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 라이센스