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.

MCP Servers