# Jupyter Notebook Editor MCP Server

A local MCP server for reading, writing, and executing Jupyter notebooks. Uses `jupyter_client` via ZMQ to communicate directly with kernels — no Jupyter server required.

## Features

### Notebook File Tools
| Tool | Description |
|------|-------------|
| `read_notebook` | Read notebook structure and summary |
| `get_cell_content` | Get content of a specific cell by index |
| `create_notebook` | Create a new empty notebook |
| `add_cell` | Add a cell (code/markdown/raw) |
| `edit_cell` | Edit an existing cell's content |
| `delete_cell` | Delete a cell by index |

### Kernel Execution Tools
| Tool | Description |
|------|-------------|
| `start_kernel` | Start a new Jupyter kernel |
| `list_kernels` | List all running kernels |
| `shutdown_kernel` | Shutdown a running kernel |
| `execute_code` | Execute code in a kernel |
| `execute_cell` | Execute a notebook cell and save outputs back to the file |

## Architecture

```
MCP Server (TypeScript)
    │
    ├── notebook-file.ts   — read/write .ipynb files
    │
    └── kernel-exec.ts     — kernel lifecycle & execution
            │
            └── kernel_helper.py  — Python long-running process
                    │
                    └── jupyter_client (ZMQ)  — direct kernel communication
```

The MCP server spawns a Python helper process that manages kernels via `jupyter_client`. Commands are sent over stdin/stdout as JSON, avoiding HTTP/CSRF issues entirely.

## Setup

### Prerequisites
- Node.js 18+
- Python 3.8+ with `jupyter_client` installed

```bash
pip install jupyter_client
```

### Install & Run

```bash
npm install
npm run dev       # development (tsx)
npm run build     # compile TypeScript
npm start         # production (node dist/index.js)
```

### MCP Client Configuration

```json
{
  "mcpServers": {
    "notebook-editor": {
      "command": "npx",
      "args": ["tsx", "/path/to/mcp-servers/notebook-editor/src/index.ts"]
    }
  }
}
```

## Usage

### Execute a single cell
```
start_kernel(name="python3")           → kernel_id
execute_cell(file_path="demo.ipynb", cell_index=0, kernel_id="<id>")
shutdown_kernel(kernel_id="<id>")
```

### Execute multiple cells with shared state
```
start_kernel(name="python3")           → kernel_id
execute_cell(file_path="demo.ipynb", cell_index=0, kernel_id="<id>")
execute_cell(file_path="demo.ipynb", cell_index=1, kernel_id="<id>")
execute_cell(file_path="demo.ipynb", cell_index=2, kernel_id="<id>")
shutdown_kernel(kernel_id="<id>")
```

### Auto-start kernel (single cell)
```
execute_cell(file_path="demo.ipynb", cell_index=0)
# Kernel auto-starts and shuts down after execution
```

## Development

```bash
npm install
npm run dev
```

## License

MIT