jupyter-mcp

# Jupyter Notebook MCP Server Gives Claude Code structured tools to navigate and edit `.ipynb` files without parsing raw JSON. ## Tools | Tool | What it does | | ---------------------------------- | --------------------------------------------------------- | | `notebook_overview` | All cells with index, id, type, first line | | `notebook_list_headings` | All markdown headings with level and cell index | | `notebook_get_cells_under_heading` | Cells belonging to a named section | | `notebook_get_cell` | Full source + rendered outputs of one cell | | `notebook_get_cell_by_id` | Same, but look up by nbformat cell ID | | `notebook_search_cells` | Find cells containing a string | | `notebook_edit_cell` | Replace the source of a cell | | `notebook_insert_cell` | Insert a new code or markdown cell | | `notebook_delete_cell` | Delete a cell | | `notebook_move_cell` | Reorder cells | | `notebook_clear_outputs` | Clear outputs (one cell or whole notebook) | | `notebook_execute` | Execute the whole notebook via `uv run jupyter nbconvert` | | `notebook_execute_cells` | Execute a slice of cells and patch outputs back in-place | ## Setup ### 1. Install dependencies ```bash pip install mcp ``` Or into a dedicated venv: ```bash python -m venv .venv source .venv/bin/activate pip install mcp ``` ### 2. Register with Claude Code ```bash claude mcp add notebook-editor -- python /path/to/server.py ``` Or add it to your project's `.claude/mcp.json`: ```json { "mcpServers": { "notebook-editor": { "command": "python", "args": ["/absolute/path/to/server.py"] } } } ``` Use the absolute path. If using a venv: ```json { "mcpServers": { "notebook-editor": { "command": "/absolute/path/to/.venv/bin/python", "args": ["/absolute/path/to/server.py"] } } } ``` ### 3. CLAUDE.md example ``` ## Jupyter Notebooks Always use the `notebook-editor` MCP tools when working with .ipynb files. Start with `notebook_overview`, then `notebook_list_headings` to orient yourself. ``` ### 4. Verify Start Claude Code and run: ``` /mcp ``` You should see `notebook-editor` listed with all 11 tools. ## Example Claude Code session Once registered, you can ask Claude Code things like: - "Give me an overview of analysis.ipynb" - "Show me all cells under the 'Data Cleaning' heading" - "Edit cell 4 to rename the variable from df to df_raw" - "Insert a markdown cell after cell 7 explaining the next section" - "Search for all cells that use pd.read_csv" - "Clear all outputs in the notebook" ## Notes - Edits are written immediately to disk. Keep your notebook in version control (git) before letting Claude Code make bulk changes. - Outputs are not cleared automatically on edit; call `notebook_clear_outputs` explicitly if you want a clean state before re-running. - `notebook_execute` requires `uv` and `jupyter` to be available in your environment. Install with `uv add jupyter nbconvert` or `pip install nbconvert`. - `notebook_execute_cells` is useful after editing a section - it runs only the affected cells and patches their outputs back, so you do not have to wait for the whole notebook to re-execute. - Execution errors are reported per-cell in the return value. Claude Code can immediately call `notebook_get_cell` on a failed cell to read the traceback and attempt a fix.