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

pip install mcp

Or into a dedicated venv:

python -m venv .venv
source .venv/bin/activate
pip install mcp

2. Register with Claude Code

claude mcp add notebook-editor -- python /path/to/server.py

Or add it to your project's .claude/mcp.json:

{
  "mcpServers": {
    "notebook-editor": {
      "command": "python",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}

Use the absolute path. If using a venv:

{
  "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.