Skip to main content
Glama
Sign In
jupyter_mcp

jupyter_mcp

by Liu-Eroteme
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

jupyter-mcp

Kernel-attached MCP server for Jupyter EDA workflows. Built for coding agents that iterate on notebooks: named cells, a dependency DAG, minimal re-execution, condensed outputs, and cheap LLM summaries for navigation.

Why

Editing notebooks through generic file tools is painful for agents:

  • cells have no stable, human-meaningful addresses

  • every change means re-executing the whole notebook from scratch

  • raw outputs (box-drawn tables, base64 charts, ANSI noise) flood context

  • nothing tells you which cells a change invalidates

This server fixes each of those with an opinionated data model.

Related MCP server: Jupyter MCP Server

Concepts

Concept

What it means

Cell names

Every cell has a unique kebab-case name stored in cell.metadata.jupyter_mcp.name. Unnamed cells get auto-names from their first comment/heading.

Revisions

Each cell has a short content hash (rev). Every mutation requires the expected_rev from your latest read — optimistic locking that makes wrong-target and stale edits structurally impossible. No confirmation round-trips.

Dependency DAG

A static AST pass (not runtime tracing) extracts per-cell defines/uses/mutations and builds last-writer-wins edges. Works on unexecuted cells, which is the whole point: edit first, then run.

Staleness

A cell is fresh only if its current source ran on the currently live kernel (freshness is stamped with a per-kernel epoch). Source edits make a cell and its dependents stale; a new or restarted kernel makes everything stale — persisted metadata can never claim freshness against empty kernel state. run executes exactly the stale set, in document order.

Background execution

Every run goes through a per-notebook executor thread. run waits a bounded time (default 60 s); anything longer keeps executing while outputs accumulate in a live buffer — the overview shows RUNNING/QUEUED, read_cells returns output-so-far, interrupt stops it. Oversized output keeps head+tail with explicit dropped markers.

Condensed outputs

Streams merged, ANSI stripped, long text truncated head+tail with explicit markers. Duplicate table reprs collapse to one: uniform → CSV, ragged → JSON. Charts return as real MCP images (downscaled), so the agent sees them.

Summaries

Lazy, batched claude-haiku-4-5 summaries (tldr + description + output summary) cached in cell metadata keyed by content hash. Unchanged cells are never re-summarized. Degrades to deterministic fallbacks (marked *) without API credentials.

Snapshots / undo

Every mutation snapshots the file first (under ~/.cache/jupyter_mcp/); undo_last restores it.

Tools

Tool

Purpose

create_notebook

New empty notebook

notebook_overview

Index: names, revs, staleness, tldrs, edges, lint

read_cells

Full cells (code + condensed outputs + images), by names/slice

add_cell / update_cell / remove_cell / move_cell

Mutations; all take expected_rev; add/update accept run="stale" to fold the edit→run loop into one call

run

Default: all stale cells (minimal recompute). With cells: exactly those, even if fresh, after freshening their stale ancestors (fresh_deps). Bounded wait; continues in background

interrupt

Stop the running cell (KeyboardInterrupt), cancel the queue

restart_kernel

Fresh kernel; marks everything stale

inspect_variable

Type/shape/schema of a live variable plus its richest repr: dataframes as CSV, figures as images, else pretty repr

undo_last

Restore pre-mutation snapshot

summarize_cells

Detailed LLM summaries incl. outputs

search_cells

Search source + names + summaries

Setup

uv sync

Register with Claude Code (.mcp.json in any project, or globally):

{
  "mcpServers": {
    "jupyter": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/jupyter_mcp", "jupyter-mcp"]
    }
  }
}

The server is multi-notebook: every tool takes a notebook path, one kernel per notebook, started lazily in the notebook's directory (so relative data paths behave like in your editor). Kernelspec comes from the notebook's metadata, falling back to python3. Kernels idle longer than 30 minutes are shut down lazily (JUPYTER_MCP_KERNEL_TTL_SECONDS overrides); the next execution restarts them, and epoch-scoped staleness handles the rest. On POSIX, kernels connect over IPC sockets (no open TCP ports).

Summaries & credentials

Summaries use the plain anthropic SDK: credentials resolve from ANTHROPIC_API_KEY or an ant auth login profile automatically. Cost is negligible (Haiku, batched, hash-cached). To disable entirely set JUPYTER_MCP_DISABLE_SUMMARIES=1 — everything else works unchanged.

Development

uv run pytest              # full suite
uv run pytest -m "not kernel"   # skip real-kernel integration tests

Layout: src/jupyter_mcp/ is a plain library (model, dag, condense, kernel, summaries, session) with the MCP surface isolated in server.py; everything below the server is unit-testable without MCP.

Known limitations (v1)

  • The DAG is static: dynamic patterns (globals()[name] = ..., exec, attribute mutation through aliases) are invisible. Method calls only count as mutations for a known allowlist (append, fit, ...) — pure-functional chains (polars) intentionally create no false forward edges.

  • %%bash / %%sql style cells are treated as opaque (no dependencies).

  • Concurrent edits from a live Jupyter editor are detected (the server reloads and rejects the mutation) but not merged.

See docs/ROADMAP.md for what's deliberately deferred — including the phase-2 OKF knowledge base.

Available Tools

14 tools
add_cellA

Add a cell. name must be unique kebab-case. Placement: after (an existing cell name; '' prepends), index, or omit both to append. run="stale" immediately executes every stale cell (the add→run loop in one call) and returns the execution results.

Inputs: name (required), path (required), source (required), run, +3 more.

create_notebookA

Create a new empty notebook at path (must not exist yet).

Inputs: path (required), kernel_name. Returns: result

inspect_variableA

Inspect a live kernel variable without adding a cell: type, shape, schema/columns, length, plus its richest Jupyter repr — dataframes condense to a CSV table, figures come back as images, everything else falls back to a (pretty) repr.

Inputs: path (required), variable (required), timeout_seconds.

interruptA

Interrupt the currently running cell (KeyboardInterrupt in the kernel) and cancel queued cells. Kernel state (variables) survives; interrupted cells read as stale until a successful re-run.

Inputs: path (required), clear_queue. Returns: result

move_cellB

Move a cell: after an existing cell ('' moves to top) or to index.

Inputs: name (required), path (required), expected_rev (required), after, +1 more. Returns: result

notebook_overviewA

Index of the notebook: one line per cell (index, name, revision, staleness, one-line summary) plus dependency edges and lint findings. Start here when opening a notebook. Summaries marked with * are deterministic fallbacks, not LLM-generated.

Inputs: path (required), refresh_summaries. Returns: result

read_cellsA

Read cells with code and condensed outputs (charts attached as images). Select by names (list of cell names), indices (python slice string like '0:5'), or neither for the whole notebook. view: full | code | outputs.

Inputs: path (required), view, names, indices.

remove_cellA

Delete a cell (requires its current rev; undo with undo_last).

Inputs: name (required), path (required), expected_rev (required). Returns: result

restart_kernelA

Restart the notebook's kernel (all in-memory state is lost; every code cell becomes stale).

Inputs: path (required). Returns: result

runA

Execute cells on the notebook's persistent kernel.

Default (no `cells`): every stale cell in document order — minimal
recompute after edits. With `cells`: exactly those cells, even if fresh
(API calls, randomness), preceded by their stale ancestors so inputs are
trustworthy (`fresh_deps=false` skips the ancestor pass). Outputs are
persisted and returned condensed; charts come back as images; `quiet`
collapses ok cells to status lines. If everything finishes within
`wait_seconds` you get full results; otherwise execution continues in the
background — watch it via notebook_overview / read_cells (live output),
stop it via interrupt.

Inputs: path (required), cells, quiet, fresh_deps, +2 more.

search_cellsB

Search cell sources, names, summaries, and condensed outputs. Returns matching cells with the matching lines.

Inputs: path (required), query (required), regex. Returns: result

summarize_cellsC

Detailed summaries (LLM): per-cell description plus, optionally, a summary of each cell's current output. Cheaper than reading full cells when orienting in a large notebook.

Inputs: path (required), names, include_outputs. Returns: result

undo_lastB

Restore the notebook to its state before the most recent mutation.

Inputs: path (required). Returns: result

update_cellA

Replace a cell's source and/or rename it. expected_rev must be the rev from your latest read of this cell (optimistic locking). Updating source clears the cell's outputs and marks it (and dependents) stale. run="stale" immediately executes every stale cell (the edit→run loop in one call) and returns the execution results.

Inputs: name (required), path (required), expected_rev (required), run, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

    TDQS

    A3.8/5.0

    Scored across 14 tools

    Disambiguation5/5

    Each tool has a clear, distinct purpose with minimal overlap. The only potential ambiguity is between add_cell's run option and the run tool, but their primary functions are sufficiently different.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (e.g., add_cell, create_notebook, inspect_variable). The only minor deviation is undo_last (verb_adverb), but it remains consistent with the overall style.

    Tool Count5/5

    With 14 tools, the set is well-scoped for a Jupyter notebook server. It covers creation, editing, execution, inspection, and undo operations without being excessive or insufficient.

    Completeness4/5

    The tool surface covers the core notebook lifecycle (CRUD, execution, inspection, undo). However, there is no explicit save or export tool, which is a minor gap assuming automatic persistence.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • JupyterMCP

      ilylty
      F
      license
      Not graded
      quality
      D
      maintenance
      A Model Control Protocol (MCP) server that enables remote programmatic control of Jupyter notebooks, allowing AI assistants and applications to create, edit, and execute notebook cells via SSE protocol.
      -

    • notebook-agent-mcp

      KJH-Sun
      F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to execute Jupyter notebook cells with persistent kernel state, output persistence, and structured JSON control surface.
      2
      -