jupyter-rmcp

Run ad-hoc Python in the kernel (stateful; variables persist across calls) and **append** it as a new cell to the bound notebook (if any). For iterating on an EXISTING cell without duplicating it, use execute_cell / edit_cell instead. On timeout the kernel is interrupted. Works for local and colab b…

Poll a background job started by execute_code(background=True): returns its `status` ("running_in_background" / "done" / "error" / "unknown") and a WINDOW of the stdout+stderr it has captured (unbuffered — live progress shows). Cheap, non-blocking; call repeatedly until status is no longer "running_…

List running kernels across all backends (local + registered Colab), with their backend, notebook binding, state, idle/age seconds, and pin status.

Start a notebook kernel and return its kernel_id (use it with execute_code / add_cell / execute_cell). Work is saved to a notebook ON THE SERVER (viewable/editable in JupyterLab).

Terminate a kernel (and its session, if any) and free its resources. For a COLAB kernel this DESTROYS the VM — all /content files and pip installs on it are lost, and a later start_kernel gives a brand-new empty VM. To merely reset Python state while keeping the VM + files, use restart_kernel instea…

Restart a kernel, clearing all in-memory state (variables) but keeping the same id. For a COLAB kernel this restarts ONLY the Python process — the VM survives, so /content files, the HuggingFace/model cache and pip-installed packages persist; just the interpreter (and its module cache) is fresh. Use…

Interrupt a running kernel (raise KeyboardInterrupt) to stop a runaway execution. LOCAL kernels only — Colab has no interrupt.

Review a COLAB session's recent COMPLETED executions — each one's code AND the output it captured — WITHOUT re-running anything. Handy to retrieve a past cell's result or confirm what already ran on the VM. `limit` = how many recent executions to return. IMPORTANT: an execution is logged only when i…

Pin/unpin a kernel to exempt it from the IDLE reaper (e.g. a long-lived notebook). Note: pinning does NOT exempt it from the absolute max-age hard cap (KERNEL_MAX_AGE_SEC) — nothing lives past that. Pin state persists across MCP restarts (kept in the kernel registry).

List the user-defined variables currently held in the kernel (name/type/size).

List available compute backends for start_kernel: `local` (the server's own Jupyter) and `colab` (official colab-cli, GPU on demand) if configured. Shows kind, reachability, and `exec_enabled` — false for `local` when the server runs colab-only, meaning it still stores/serves notebooks but refuses t…

Current revision token of a notebook: {path, rev, cells}. `rev` is a content hash — pass it as `expected_rev` to an editing tool to guard against a concurrent external edit (e.g. a human in JupyterLab). Mutating tools also return the new rev.

Overview of a notebook's cells (no full source): per cell {index, id, type, summary, num_lines, has_outputs, has_error}. `id` is stable across insert/delete/ move — prefer addressing later edits by `id`. Also returns the notebook `rev`.

Read full source (+ a text summary of outputs) for specific cells, by `indices` OR `ids` (batch — one round-trip). Omit both to read all cells.

Insert several cells at once, contiguously BEFORE `index` (index == cell count appends). `cells` = list of {cell_type, source, summary?}. Prefer this over many single inserts. Returns {indices, ids, rev}.

Insert one cell BEFORE `index` (index == cell count appends). For a block of cells prefer insert_cells. Returns {index, id, rev}.

PREFERRED edit: replace a UNIQUE `old` substring with `new` in one cell (cheap — no full-source resend). Target by `cell_id` (stable, preferred) OR `index`. `old` must occur exactly once in the cell, else it errors (safer than a wrong guess). Does not touch outputs. Returns {index, id, rev}.

Replace a cell's ENTIRE source (for small changes prefer patch_cell). Target by `cell_id` (preferred) OR `index`. `summary` sets metadata summary ("" clears). Does not execute or touch outputs. Returns {index, id, rev}.

Delete a cell, addressed by `cell_id` (preferred) OR `index`. Returns {rev, remaining}.

Move a cell to `to_index` (final 0-based position). Address the moved cell by `from_id` (preferred) OR `from_index`. Returns {rev}.

Run an EXISTING code cell in the kernel's bound notebook and update THAT cell's outputs in place (no duplicate). Target by `cell_id` (stable, preferred) OR `index`. Editing (patch_cell/edit_cell) is separate — this only runs a cell as-is.

Create a new notebook (.ipynb) under the work root, optionally seeded with `cells` (list of {cell_type, source, summary?}). To inspect/edit existing notebooks use list_cells / read_cells / patch_cell etc.

Make Kaggle usable in this kernel (`!kaggle datasets download …`). For LOCAL kernels this is already configured (no-op). For a COLAB kernel it injects the server-side token into that Colab VM: the token is uploaded as a file and loaded into the VM env (`KAGGLE_API_TOKEN`) + `~/.kaggle/`, so it never…

Make a HuggingFace token available in this kernel WITHOUT it appearing in exec/session history — needed for gated/private repos (`hf_hub_download`, `from_pretrained`). Same masked-injection design as setup_kaggle: for a COLAB kernel the token is uploaded as a file and loaded into the VM env (`HF_TOK…

Copy a file from the server workspace (uploaded via JupyterLab / upload_file / fetch_to_workspace) ONTO the Colab VM for this kernel, so the notebook can open it there. `remote_path` defaults to /content/<basename>. Local kernels already see workspace files directly (no copy needed).

Copy a file FROM the Colab VM (e.g. a result/checkpoint the notebook produced) back into the server workspace so it persists and is visible in JupyterLab. `workspace_path` defaults to the remote basename at the work root. Colab kernels only.

List notebooks and subdirectories under `path` (relative to the work root). For ALL files (data, images, etc.) use list_files.

List EVERYTHING (files + folders) under `path` in the workspace — notebooks, uploaded data, images, etc. Files live on the server (persistent) and are visible to kernels (cwd is the work root) and in JupyterLab.

Create a folder (and any missing parent folders) under the work root. Notebook/ file writes also auto-create parents, so you rarely need this explicitly.

Write a file into the workspace from base64 bytes (binary-safe; persists on the server, visible to kernels and JupyterLab). Auto-creates parent folders. For a human uploading from a phone/laptop, JupyterLab's Upload button is usually easier; use this when a client can provide the bytes (e.g. Claude …

Download a URL to a file in the workspace, server-side (the server fetches it). Handy to bring in a test image/dataset by link when you can't upload from the device. Auto-creates parent folders; capped at 200 MB.