notebook-tools-mcp

MCP server for Jupyter notebook navigation and editing. Reads .ipynb files directly as JSON — no Jupyter server, no kernel, no overhead.

Problem

AI CLI agents (Claude Code, Gemini CLI, Codex) working inside VS Code Dev Containers don't have a good way of interacting with Jupyter notebooks. Notebooks are JSON files where 90%+ of the bytes are base64-encoded image outputs and execution metadata. Reading a 1MB notebook with a standard file-read tool wastes ~294K tokens on noise. Agents re-invent notebook parsing logic every session, burning tokens on the same problem repeatedly.

Architecture

6 files, ~700 lines, zero dependencies beyond mcp>=1.10.1:

notebook_tools_mcp/
  __init__.py      (35L)  FastMCP instance + server instructions
  _helpers.py      (182L) Shared utilities: load/save, cell formatting, parsing
  read_tools.py    (251L) 6 read tools
  search_tools.py  (126L) 2 search tools
  write_tools.py   (104L) 3 write tools
  server.py        (16L)  Entry point

Each file < 260 lines. Single responsibility. Shared helpers avoid duplication. No circular imports.

Design decisions

No Jupyter server. Works in remote VS Code Dev Containers (Docker) over SSH. Adding a Jupyter server means extra memory, extra complexity, zero value when VS Code already renders notebooks natively.

No dependencies beyond mcp. Notebooks are JSON. Python's stdlib json module reads them perfectly. nbformat (and its 50+ transitive Jupyter ecosystem deps) is unnecessary weight.

No execution. Running code requires a kernel, which requires a server. That's the complexity this tool exists to avoid.

stdio transport only. Launched on demand by the MCP client, communicates via stdin/stdout, exits when done. No HTTP endpoints, no WebSocket connections, no persistent processes.

Consistent index-based addressing. All 11 tools use integer cell indices. nb_overview shows indices → nb_read_cell(15) reads → nb_write_cell(15, ...) edits. One addressing scheme throughout.

sort_keys=True on save. Matches Jupyter/nbformat convention for deterministic output. Prevents noisy git diffs from key reordering between load/save cycles.

Write tools vs NotebookEdit

Claude Code has a built-in NotebookEdit tool (addresses cells by cell_id or cell_number). This server also provides write tools. Both are kept intentionally:

	MCP write tools	NotebookEdit (built-in)
Addressing	Integer index (matches nb_overview)	cell_id string or cell_number (0-indexed)
Best for	Within the nb_overview → read → edit flow	When VS Code or another tool provides the cell_id
Footprint	102 lines	Built-in

The MCP write tools exist for workflow cohesion — an agent using nb_overview to find a cell already has its index. Requiring a lookup to get the cell_id for NotebookEdit would add a pointless extra step.

Tools we deliberately did NOT build

These were considered and rejected because nb_search / nb_search_dir already cover them:

Rejected tool	Why nb_search is sufficient
nb_dependencies(var)	nb_search(path, "var_name") returns definitions and usages; LLMs trivially distinguish x = ... from ...x...
nb_function_map	nb_search_dir(dir, "^def\\s+\\w+", cell_type="code")
nb_imports_all	nb_search_dir(dir, "^import|^from\\s+\\w+\\s+import")
nb_compare_cells	Agent calls nb_read_cell twice

Building AST-based dependency tracking would add ~200+ lines of fragile code that breaks across Python/R/Julia/bash cells. Not worth it when regex search + LLM reasoning achieves the same result.

How agents discover when to use these tools

Claude Code (and similar agents) decide which tool to use based on three channels, in order of priority:

1. MCP server instructions — set via FastMCP(instructions=...) in __init__.py. Injected into the system prompt of every conversation where the server is connected. This is where the "use nb_search INSTEAD OF Grep for .ipynb" guidance lives. Agents see this before any tool is called.

2. Tool docstrings — the """...""" on each @mcp.tool() function. Shown when the agent discovers tools (e.g. via ToolSearch). Each docstring says what the tool does AND when to prefer it over alternatives.

3. CLAUDE.md — project-level instructions always loaded into context. Contains a decision table mapping tasks to tools (e.g. "Read notebook → nb_overview, NOT Read tool").

All three channels reinforce the same message: use nb_* tools for .ipynb, never Read/Grep.

Install

# pip
pip install git+https://github.com/tony-zhelonkin/notebook-tools-mcp.git

# uv
uv pip install git+https://github.com/tony-zhelonkin/notebook-tools-mcp.git

For development (editable install from a local clone):

git clone https://github.com/tony-zhelonkin/notebook-tools-mcp.git
pip install -e notebook-tools-mcp/

Configure

Add to .mcp.json:

{
  "mcpServers": {
    "notebook-tools": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "notebook_tools_mcp.server"]
    }
  }
}

Or toggle via SciAgent-toolkit addon system:

./scripts/manage-addon.sh enable notebook-tools --project-dir /path/to/project
./scripts/manage-addon.sh disable notebook-tools --project-dir /path/to/project

Tools

All tools take notebook_path (absolute path) as first parameter unless noted.

Read tools

Tool	Parameters	What it does
nb_metadata	notebook_path	Kernel info, format version, cell counts, file size, output size
nb_overview	notebook_path, include_output_sizes=true	Cell index, type, line/char count, first-line preview, output sizes
nb_read_cell	notebook_path, cell_index, include_outputs=false, max_output_chars=2000	Full source of one cell by index, optional truncated outputs
nb_read_cells	notebook_path, cell_indices (e.g. "0,1,5-8"), cell_type=null, include_outputs=false	Batch read with range syntax, optional type filter
nb_read_section	notebook_path, header, max_cells=50, include_outputs=false	All cells from a markdown heading to the next same-or-higher-level heading
nb_headings	notebook_path	All markdown headings with cell indices and levels

Search tools

Tool	Parameters	What it does
nb_search	notebook_path, pattern (regex), cell_type=null, context_lines=1	Regex search across cells with context, optional type filter
nb_search_dir	directory, pattern (regex), cell_type=null, context_lines=0	Search all .ipynb files in a directory, grouped by notebook

Write tools

Tool	Parameters	What it does
nb_write_cell	notebook_path, cell_index, source	Overwrite source content of an existing cell
nb_insert_cell	notebook_path, cell_index (-1 to append), cell_type, source	Insert a new cell at position
nb_delete_cell	notebook_path, cell_index	Delete a cell

Typical agent workflow

1. nb_metadata(path)              → Is this notebook big? What kernel?
2. nb_overview(path)              → See all cells at a glance (index, type, preview)
3. nb_headings(path)              → Understand section structure
4. nb_search(path, "pattern")     → Find cells containing a variable/function/import
5. nb_read_cell(path, 15)         → Read the specific cell you need
6. nb_read_cells(path, "15-20")   → Read a range of related cells
7. nb_read_section(path, "Results") → Read everything under a heading
8. nb_write_cell(path, 15, src)   → Edit the cell in-place

The key insight: start with nb_overview, then drill down. Never read the full notebook.

Token economics

Tested against real project notebooks:

Notebook	File size	Cells	Full Read tool	nb_overview	nb_read_cell	nb_search
NB00 (smallest)	51 KB	30	~13K tokens	~500 tokens	~50-200 tokens	~100 tokens
NB01 (biggest)	1.15 MB	41	~294K tokens	~690 tokens	~100-400 tokens	~50-200 tokens

For the 1.15 MB notebook, nb_overview achieves ~425x token reduction vs reading the full file. Individual cell reads achieve ~700-2900x reduction.

CLAUDE.md snippet

Add this to your project's CLAUDE.md to steer Claude Code toward using notebook-tools instead of built-in tools for .ipynb files. The server also ships its own instructions (injected into the system prompt automatically), but CLAUDE.md reinforcement ensures consistent behavior, especially when agents are choosing between several tools.

### Working with .ipynb files

**ALWAYS use `notebook-tools` MCP tools instead of built-in tools for `.ipynb` files:**

| Task | Use this | NOT this | Why |
|------|----------|----------|-----|
| Read notebook | `nb_overview` then `nb_read_cell` | `Read` tool | Read loads raw JSON with base64 images, wastes 100K+ tokens |
| Search notebook | `nb_search` / `nb_search_dir` | `Grep` tool | Grep sees JSON structure, nb_search sees cell source code |
| Edit notebook cell | `nb_write_cell` (by index from nb_overview) | — | Consistent index-based workflow |
| Edit notebook cell | `NotebookEdit` (by cell_id) | — | Use when cell_id is known from another source |
| Insert/delete cells | `nb_insert_cell` / `nb_delete_cell` | — | Index-based, consistent with nb_overview |

**Workflow:** `nb_overview` (get cell indices) → `nb_read_cell` or `nb_search` → `nb_write_cell`.

All 11 tools are in the `notebook-tools` MCP server. Start with `nb_overview` for any notebook interaction.

When NotebookEdit is the better choice

The MCP write tools and Claude Code's built-in NotebookEdit solve the same problem (editing notebook cells) with different addressing:

• MCP nb_write_cell: addresses by integer index. Best when you're already in the nb_overview → nb_read_cell → edit flow, because you already have the index.
• NotebookEdit: addresses by cell_id (a string like "abc123") or cell_number (0-indexed integer). Best when something else gives you the cell_id — for example, VS Code's notebook renderer, or the id field shown in nb_read_cell output.

In practice, MCP write tools are used more often because the typical agent workflow starts with nb_overview, which shows indices. NotebookEdit is better when the agent already has a cell_id from a non-MCP source, or when it needs NotebookEdit's edit_mode: "insert" semantics (insert after a specific cell_id rather than at an index position).

Both tools can coexist safely. The server's instructions field tells agents to prefer MCP write tools during the nb_overview workflow. There is no conflict as long as the agent doesn't use both on the same cell in the same turn.

Changelog

v0.3.0 (2026-02-25)

• Fix: Added sort_keys=True to save_notebook for deterministic JSON output matching Jupyter/nbformat convention
• Agent guidance: Added FastMCP(instructions=...) with tool selection decision tree (injected into agent system prompt)
• Agent guidance: Rewrote all 11 tool docstrings to specify when to use each tool vs built-in alternatives
• Doc: Documented write tools relationship to Claude Code's built-in NotebookEdit
• Doc: Added "How agents discover when to use these tools" section explaining the 3-channel guidance pattern

v0.2.0 (2026-02-25)

• Added write tools: nb_write_cell, nb_insert_cell, nb_delete_cell
• Modularized into 6-file architecture
• Added nb_headings, nb_read_section, nb_search_dir

v0.1.0

• Initial release: nb_metadata, nb_overview, nb_read_cell, nb_read_cells, nb_search