# jupyterlab-collab-mcp [Health: Active]

**Category:** 👨‍💻 Code Execution  
**Repository:** https://github.com/ianhi/jupyterlab-collab-mcp  
**GitHub Stars:** 7  
**npm Downloads (last month):** 385  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/jupyterlab-collab-mcp

## Description
MCP server for real-time JupyterLab notebook collaboration

## Tools
Capabilities this server exposes over MCP:

- **connect_jupyter** — Connect to JupyterLab for real-time sync and kernel execution. Without connecting, tools still work by reading .ipynb files directly.
- **list_files** — List files and directories. Use to discover notebooks.
- **list_notebooks** — List notebooks with running kernels. Use list_files for all .ipynb files regardless of kernel state.
- **list_kernels** — List available kernel types (e.g., python3, ir) and running instances.
- **troubleshoot** — Diagnose why notebook edits may not be syncing or persisting. Reports connection/RTC health and, for a given notebook, sync state, browser peers, a forced-save result, and a disk-vs-room round-trip check that detects split-brain (wrong/second server). Use when edits don't show up in the browser or on disk.
- **save_notebook** — Force a verified save of the notebook's live collaboration room to disk and report whether it persisted (success/skipped/failed). Use this to guarantee edits reach disk — NEVER edit the .ipynb file directly to 'save' it, as a direct file write is reverted by jupyter-collaboration and loses in-room edits.
- **open_notebook** — Open a notebook and start a kernel. Safe to call if already open. Required before executing cells.
- **create_notebook** — Create a new notebook. Optionally open it with a kernel.
- **get_notebook_content** — Read cells from a notebook. Returns source only (no outputs) by default. Set include_outputs=true to see results.
- **get_notebook_outline** — Condensed notebook structure: markdown headers by level + code cell previews. Use to find cell indices.
- **search_notebook** — Grep through notebook cells (regex). Returns matching cells with context.
- **replace_in_notebook** — Search and replace across cells. Returns replacement count per cell.
- **rename_symbol** — Scope-aware Python rename across all cells. Won't rename in strings/comments.
- **get_diagnostics** — Static code diagnostics (errors, warnings) without executing. Uses LSP or Python syntax checking.
- **get_hover_info** — Documentation/type info for code at a position. Uses LSP or kernel introspection.
- **get_user_focus** — Which cell the user is editing (cursor position via awareness protocol). Returns null if no active user.
- **insert_cell** — Insert a cell. Set execute=true to run it immediately and return its output — a single-call, durable alternative to execute_code (code+output are saved in the notebook and visible to the human). Supports handoff_after_ms for long runs.
- **update_cell** — Update a cell's source. Set execute=true to run it after updating.
- **batch_update_cells** — Update multiple cells atomically. More efficient than repeated update_cell.
- **batch_insert_cells** — Insert multiple cells at once, applied in order. Each `index` is the literal position in the notebook as it stands at that step (after earlier inserts in this batch). For a contiguous block, pass increasing indices (e.g. 20, 21, 22) or anchor with `cell_id`. Omit index to append.
- **delete_cell** — Delete cells. Single: index or cell_id. Batch: indices[], cell_ids[], or start_index+end_index.
- **change_cell_type** — Convert cell type (code <-> markdown) in place.
- **copy_cells** — Copy or move cells between notebooks. Set delete_source=true to move.
- **execute_cell** — Execute notebook cells. Single cell: use index/cell_id. Range: add end_index. By IDs: use cell_ids[]. Skips non-code cells in range mode.
- **execute_code** — Run throwaway code in the kernel without modifying the notebook — for quick probes whose output you don't need to keep. Output is NOT saved and only briefly retained. For anything worth keeping or showing a human, prefer insert_cell(execute=true): same single call, but code+output are saved in the notebook.
- **get_cell_run_output** — Fetch output for a run started by execute_cell/execute_code (typically one that handed off via handoff_after_ms). Works for runs still executing AND completed runs — also the right tool to call when a <channel source="jupyter"> notification fires.
- **list_runs** — List recent kernel runs (from execute_cell/execute_code) and their states (queued/running/handed_off/completed/failed), most-recent-first. Use this to discover a run_id or check whether a handed-off run is still executing vs. finished vs. evicted, instead of blindly holding an id that may be gone.
- **clear_outputs** — Clear execution outputs. Omit index to clear all cells.
- **get_cell_outputs** — Read cell outputs without source code. Supports single cell, range, or non-contiguous selection.
- **filter_output** — Filter cached execution output with grep/head/tail. Use after execute_cell or execute_code — avoids re-executing.
- **cell_metadata** — Get or set cell metadata. Omit 'metadata' to GET, provide to SET (merges, null deletes keys).
- **cell_tags** — Add, remove, or find tags on cells. Common: 'hide-input', 'hide-output', 'parameters'.
- **notebook_metadata** — Get or set notebook-level metadata. Omit 'metadata' to GET, provide to SET.
- **kernel** — Kernel control: status, interrupt, or restart.
- **kernel_variables** — List or inspect kernel variables. Without 'names': lists all. With 'names': deep inspect (columns, dtypes, shapes).
- **rename_notebook** — Rename a notebook file.
- **diff_notebooks** — Compare two notebooks cell by cell. Returns unified diff.
- **get_cell_history** — Change history for a cell: who, when, old/new content. Session-scoped.
- **get_notebook_changes** — Changes since a version number (polling pattern). Use since_version=0 for all.
- **recover_cell** — Re-insert a deleted cell from change history. Session-scoped.
- **snapshot** — Notebook snapshots: save, restore, list, or diff against current.
- **cell_locks** — Advisory cell locks: acquire, release, or list.
- **report_issue** — Report a tool bug, hang, or suggestion about this MCP server. Logs locally and returns a structured GitHub-issue draft (title + sectioned body) for ianhi/jupyterlab-collab-mcp. This project accepts fully agent-drafted issues.
- **notebook_guide** — Best practices for working with notebooks via this server. Call this FIRST when starting notebook work (or when unsure which tool to use) — returns guidance on reading, editing, executing, collaborating, and troubleshooting. Optionally pass a topic to get just one section.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "jupyterlab-collab-mcp": {
    "command": "npx",
    "args": ["-y","jupyterlab-collab-mcp"]
  }
}
```

## Documentation

## What jupyterlab-collab-mcp does

jupyterlab-collab-mcp connects an MCP-compatible AI assistant to Jupyter notebooks. Its primary workflow uses a stdio connection between the assistant and the MCP process, followed by a y-websocket connection to JupyterLab. Changes made through the assistant can appear in the open JupyterLab interface through the built-in collaboration support.

The server is designed for notebook-specific work that ordinary file editing does not cover well. It can address cells by stable IDs, work with cell content and outputs, run code through a connected kernel, and support collaboration-aware operations such as locking, change tracking, and agent attribution.

## How it works

Start JupyterLab with `jlabx`, or use `jupyter lab` when `jupyter-collaboration` is already installed. After adding the server to an MCP client, provide the JupyterLab URL, including its token when required, so the assistant can connect to the live workspace.

A live JupyterLab connection enables kernel operations and real-time synchronization. Without that connection, most tools can still read and write `.ipynb` files directly. This file-based mode does not provide kernel operations.

The server uses JupyterLab's built-in `jupyter-collaboration` functionality rather than requiring a separate JupyterLab extension from this project. `jlabx` is an optional launcher that starts JupyterLab with collaboration and other listed extensions.

## Setup and configuration

The recommended installation uses Node.js 18 or newer and `npx`:

```bash
claude mcp add -s user jupyter -- npx jupyterlab-collab-mcp
```

The package can also run through `uvx deno -A npm:jupyterlab-collab-mcp` when Node.js is not installed. For development, clone the repository, run `npm install && npm run build`, and register `node $PWD/dist/index.js` as the MCP command.

A typical session starts JupyterLab, then asks the assistant to connect to a URL such as `http://localhost:8888/lab?token=...`. The project documents Claude Code commands for registering and reconnecting the server. When developing locally, rebuild the project and reconnect the MCP server after changing tool schemas because definitions are cached at startup.

## Tools and capabilities

The tool set includes 42 operations covering:

- Reading and editing notebook cells
- Executing cells when a JupyterLab connection and kernel are available
- Searching notebook content and inspecting differences
- Applying cell tags and creating snapshots
- Locking cells for multi-agent workflows
- Tracking changes and attributing edits to agents
- Filtering by cell type, omitting outputs, and limiting image data to reduce context use

Stable cell ID addressing helps operations continue to refer to the intended cells after insertions or deletions. Collaboration features are intended for workflows where more than one agent or user may modify a notebook.

## Limitations and notes

Kernel execution depends on a live JupyterLab connection. Direct `.ipynb` file access remains available for most other operations, but it cannot execute notebook code in that mode. The server communicates with JupyterLab through y-websocket and relies on JupyterLab collaboration support being available.

The repository is licensed under BSD-3-Clause. Its development workflow uses TypeScript compilation, Vitest tests, and a separate integration test against a running JupyterLab instance.

_Full upstream README: https://allmcps.com/mcp/jupyterlab-collab-mcp/readme_