# MCP JUPYTER Server

Model Context Protocol server that exposes basic tooling for inspecting and editing Jupyter notebooks (`.ipynb`) from any MCP-compatible client.

## Features
- Read notebook cells with optional filtering by cell type.
- Add, update, or delete cells while preserving notebook metadata.
- Get quick notebook stats (cell counts, execution metadata, format version).
- Runs over stdio so it can be wired directly into MCP clients such as Claude Desktop.

## Requirements
- Node.js 18 or newer.
- Access to the `.ipynb` files you want to work with (local file paths).

## Quick start (npx)
Run directly from the repo/package without cloning:
```sh
npx -y mcp-jupyter
```

## Installation (local checkout)
```sh
npm install
```

### Example MCP client entry
Point your client at the built entrypoint (adjust the path to your checkout):
```json
 {
  "mcpServers": {
    "jupyter": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-jupyter"
      ],
      "cmd": ""
    }
  },
  "$version": 2
}
```

## Available tools

### Position-Based Operations
- **`list_cells`** - List all cells with indices and type information
- **`get_cell_source`** - Get source code of specific cells by index
- **`edit_cell_source`** - Edit cell content by index
- **`insert_cell`** - Insert new cells at specific positions
- **`delete_cell`** - Delete cells by index with automatic reindexing

### Enhanced Operations
- **`move_cell`** - Move cells between positions
- **`convert_cell_type`** - Convert between code/markdown/raw cells
- **`bulk_edit_cells`** - Perform multiple operations in a single call