ipynb-mcp-server

English | 简体中文

An MCP server that lets any AI agent read, edit and run local Jupyter notebooks — safely, with zero setup.

Who this is for

• Students. A course hands you a .ipynb full of empty cells to fill in. Let the agent read the task, write the cells and run them — and because every edit carries an anchor, an edit that races the cell you are typing in JupyterLab fails loudly instead of overwriting you.
• Data people. Your analysis is the notebook, and its outputs hold the plots and dataframes you care about. "Change this one cell and re-run just it" is the whole point: resume touches one cell, not the forty before it — and the images come back as images.
• Teachers. An assignment already lives in a notebook: let the agent read what each student's cells actually produce. It can edit a submission, but never silently — writes are anchored, atomic, and always preceded by a rolling backup.
• Anyone pointing an agent at real files. The interesting part is not that it can edit your notebook; it is that it can show you it did not corrupt it.

The three things that go wrong without it

| What happens today | What this server does instead | |---|---| | You let an agent edit your notebook while it is also open in JupyterLab, and it overwrites a cell you changed — you find out when the file is already broken. | Every source edit carries a compare-and-swap anchor (expected_source_hash or expected_text). If the file changed since the agent last read it, the edit fails without writing — and the error already contains the current hash, so one retry succeeds. Writes are atomic and always preceded by a rolling backup. | | "Run cell 87" re-runs the 40-minute training cell at the top, or the !wget that pulls 2 GB. | mode='resume' runs only the target cells in the live kernel. No kernel alive? mode='replay' silently rebuilds state from cell 0, then runs just the target — and replayed_cell_indexes tells you exactly what was re-executed. notebook_kernel(start) + resume runs one cell with zero replay. | | To use an agent at all you must first stand up JupyterLab, copy a URL, manage a token and keep it running. | Nothing to start. stdio, one line of config, no port, no token. The server talks to a Jupyter kernel directly and dies with your client. |

Install

Nothing to clone, nothing to build. The server ships as a prebuilt npm package — pick one of these three:

| How | Command | When to use it | |---|---|---| | Run on demand — recommended | npx -y ipynb-mcp-server --root /path/to/your/notebooks | You only need it inside an MCP client's config. Nothing is installed permanently; npx fetches the published package into its cache the first time. | | Install globally | npm install -g ipynb-mcp-server then ipynb-mcp-server --root /path/to/your/notebooks | You want the command on PATH, or want to pin a version (ipynb-mcp-server@<version>). | | From source | git clone https://github.com/3021244161/ipynb-mcp && cd ipynb-mcp && pnpm install && pnpm build | Only if you are changing the code — see Development. |

Requirements: Node ≥ 22 (which brings npm and npx). Python is needed only at the moment a cell actually runs, and the server finds it itself — see Interpreter selection. The installer never runs pip install and never compiles anything.

Add it to your client (60 seconds)

# 1. it is a plain stdio server — nothing to install, nothing to start
npx -y ipynb-mcp-server --root /path/to/your/notebooks
# 2. now put the one-line config below into your client and restart it

No pip install, no JupyterLab, no port, no token.

How it compares

| | Getting started | Edits that cannot silently corrupt your file | Long jobs | Maintenance | |---|---|---|---|---| | ipynb-mcp-server (this project) | one npx line, no service | CAS anchor + atomic write + rolling backup on every edit | resume / replay / one-cell resume, plus stale-cell analysis | active (2026-10) | | datalayer/jupyter-mcp-server (~1.3k★) | needs a running Jupyter Server + SERVER_URL + TOKEN (or Docker) | — | — | active (company-maintained) | | jupyter-ai-contrib/jupyter-server-mcp | Jupyter Server extension: installed into a running server | — | — | active | | jbeno/cursor-notebook-mcp (~160★) | install from PyPI/npx, operates on the file | — | — | unmaintained since 2025-11 | | jjsantos01/jupyter-notebook-mcp (~130★) | bridges a running Jupyter over WebSocket | — | — | unmaintained since 2025-04 |

— means "not promised in that project's own documentation". Every cell above states only what each project's documentation and repository show (star counts and last-push dates read from the GitHub API on 2026-10-06); this table deliberately makes no claim about what the others do not do.

Extras: stale-cell analysis (which outputs are now invalid because their inputs changed), image outputs as native MCP image blocks, background execution with polling for long runs, per-notebook kernel lifecycle management.

Client configuration

// Claude Code / Cursor / VS Code (generic MCP stdio config)
{
  "mcpServers": {
    "ipynb": {
      "command": "npx",
      "args": ["-y", "ipynb-mcp-server"],
      "env": { "IPYNB_ROOT": "/absolute/path/to/your/notebooks" }
    }
  }
}

dsh users: install the companion dsh-ipynb-mcp bundle (see dsh-ipynb-mcp/).

The server fences all paths to IPYNB_ROOT (or --root, or the process working directory). The fence refuses to start when the root is your home directory or a filesystem root — pass an explicit --root.

Configuration

Precedence: CLI flags > IPYNB_* environment variables > defaults. Boolean flags accept --no- prefixes.

| CLI | Env | Default | Description | |---|---|---|---| | --root <dir> | IPYNB_ROOT | cwd | Root directory fence | | --allow-outside-root | IPYNB_ALLOW_OUTSIDE_ROOT | false | Allow paths outside the root | | --read-only | IPYNB_READ_ONLY | false | Only notebook_read and kernel status allowed | | --images <auto\|never\|always> | IPYNB_IMAGES | auto | Image block policy (auto: images only on full-output reads and runs) | | --python <path> | IPYNB_PYTHON | auto | Explicit interpreter (failure is final) | | --kernel-idle-seconds <n> | IPYNB_KERNEL_IDLE_SECONDS | 3600 | Idle kernel reclamation | | --exec-timeout-seconds <n> | IPYNB_EXEC_TIMEOUT_SECONDS | 300 | Per-cell timeout | | --background-threshold-seconds <n> | IPYNB_BACKGROUND_THRESHOLD_SECONDS | 30 | Runs whose estimated upper bound (timeout_seconds × target cells) exceeds 10× this go background | | --backup-keep <n> | IPYNB_BACKUP_KEEP | 10 | Rolling backups per notebook | | --artifact-dir <dir> | IPYNB_ARTIFACT_DIR | platform cache | Where image artifacts are written | | --inline-text-chars <n> | IPYNB_INLINE_TEXT_CHARS | 20000 | Text output truncation threshold | | --preview-lines <n> | IPYNB_PREVIEW_LINES | 12 | Source preview lines | | --max-images-per-call <n> | IPYNB_MAX_IMAGES_PER_CALL | 20 | Image blocks per tool call | | --max-image-bytes <n> | IPYNB_MAX_IMAGE_BYTES | 20971520 | Max bytes per image | | --log-level <level> | IPYNB_LOG_LEVEL | info | stderr log level |

Startup failures (bad values, root does not exist / is your home dir / artifact dir unwritable) exit with code 2.

Numeric configuration values must be safe integers (at most 9007199254740991) within each option's range. Filesystem roots include Windows UNC share roots; choose a notebook subdirectory instead. A rejected root does not create the artifact directory.

Writes recheck the notebook's content hash after preparing the temporary file and before each rename attempt, including retries after a Windows sharing violation. Detected external edits fail with file_changed; cancellation during a retry discards the temporary file.

Malformed UTF-8 notebooks fail with parse_failed; the reader never silently substitutes characters that could later be written back.

CAS mismatch details include actual_truncated and current_source_truncated. Long text and neighbor anchors are limited to 4000 characters plus a truncation marker; current_source_hash remains complete for retrying with a hash anchor.

Cell selector endpoints must be safe integers within the notebook before ranges are expanded. mode='full' ignores the selector. Cancellation works with or without progress notifications; finished requests do not retain interrupt listeners.

With the defaults, a single-cell run is executed synchronously (its upper bound is exactly the 10× cut-off); two or more cells, or a raised --exec-timeout-seconds, return a background run_id you poll with notebook_run_status. The multiplier is DEVIATIONS.md D-015.

Running, polling and clean validation

Background status publishes the kernel ID once it is bound and each target cell's result once that cell has finished, even while a later cell is still running. Replay stays silent. Unfinished-cell output is not a completed checkpoint. Outputs are written back at the end of the run; inspect write_back and, after cancellation, shutdown or restart, wait until facts_pending is false before treating those facts as final.

For cheap repeated polling, call notebook_run_status(run_id='run-1', include_outputs='none'). It returns the existing run facts and completed-cell metadata, including each cell's status and index, with empty outputs arrays and no images or artifact writes. Omit include_outputs, or set it to 'full', to retrieve full results subject to the normal output budget. Cheap polling does not discard those stored results. After write-back you can also read individual cells with notebook_read(cell_indexes=[...], include_outputs='full').

Completion is not a success verdict. kind: 'completed' / state: 'completed' means execution orchestration has ended. Python exceptions remain executed[].status: 'error' with their tracebacks, and do not turn the call into an MCP infrastructure error. Check every cell's status. A grading check that prints a failing score without raising an exception still has status ok; inspect its actual result separately.

full runs all code cells in the existing kernel. It ignores cell_selector and preserves in-memory variables and Python's import cache. For clean validation:

1. Call notebook_kernel(action='restart', path='analysis.ipynb').
2. Call notebook_run(mode='full', path='analysis.ipynb').
3. If a background run_id is returned, poll with include_outputs='none' until the run ends and facts_pending is false. Inspect failed cell indexes via executed[].status, then retrieve the outputs you need.

Restart resets kernel memory, not files created by notebook code. Prepare those files explicitly if your validation requires it; the server does not delete them.

Interpreter selection

When a notebook needs a kernel, the interpreter is resolved by candidate chain: --python → the notebook's own metadata.kernelspec argv → .venv/venv next to the no