jupyter-mcp-agent
Provides tools for AI agents to run and edit Jupyter notebooks on a real ipykernel, including executing cells, applying cell edits, previewing variables, managing kernel lifecycle, validating notebooks, and logging run metadata.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
jupyter-mcp-agent
An MCP server that lets AI coding agents run and edit Jupyter notebooks on a real ipykernel and report exactly what ran.
jupyter-mcp-agent is a Python Model Context Protocol (MCP) server for .ipynb notebooks. An AI coding agent (Claude Code, Claude Desktop, Cursor, or any other MCP client) can run one cell, run all cells, or run up to a given cell. It can also edit cells, preview variables and restart or interrupt the kernel. Each call gets back structured JSON: a run_id, a notebook file stamp, an environment snapshot, chunked stdout/stderr and small previews. Every run is also appended to a manifest.jsonl file beside the notebook, so a person can check afterwards what the agent actually ran.
Formerly named
llm-jupyter. The old import path (llm_jupyter),python -m llm_jupyterand thellm-jupytercommand still work as aliases.
Why
Research and data work is iterative: change a small piece of code, run it, look at numbers and plots, revise. Notebooks fit that loop, but agents usually either rewrite whole scripts or drive a full Jupyter server through a browser-shaped API. This server gives a notebook agent a small, predictable set of actions on a real kernel. Results are written to disk (the .ipynb, figures, the run manifest), not just into the chat, so they can be checked later. The design notes are in docs/PRD.md and docs/IMPLEMENTATION.md.
Related MCP server: jupyter-kernel-mcp
Features
Real ipykernel execution: one pooled kernel per notebook path. Run modes are
cell_id,run_allandrun_until_cell_id, withhalt_on_error.Trustworthy run metadata: a
run_id, notebook file stamp, sources hash, Python env snapshot and kernel generation on every reply. Runs are logged append-only tomanifest.jsonl.exploreandrecordmodes are available.Notebook editing:
cells_apply(code-cell source edits) andnotebook_cells_patch(insert, delete, move or set source, applied as one batch). Edits are serialised per notebook with an exclusive lock.Inspection without blowing the context window: capped
variable_preview, chunked streams, andexecute_result/display_datapreviews. Oversized output spills to.llm_jupyter/runs/<run_id>/.Planning without a kernel:
notebook_execution_plan(structural map, companion.apynbsidecar checks) andnotebook_validate(nbformat schema).Sandboxed paths: writes stay inside the notebook's folder plus any extra
--rootsyou allow.Host quirks handled:
--process-cwdcovers MCP hosts that ignorecwd. Kernels start in the notebook's folder by default (--kernel-cwd).
MCP tools
Tool | Purpose |
| Execute exactly one of |
| Structural notebook map + companion checks, no kernel |
| Set the source of code cells by |
| Ordered insert / delete / move / set_source ops in one batch |
| Capped |
| Kernel lifecycle ( |
| Strip persisted outputs (optionally execution counts) |
| nbformat schema check; optionally persist cell ids |
| No-kernel smoke test: version, tools, Python path, cwd, allowed roots |
Quick start
Requires Python 3.10+.
git clone https://github.com/goelanmol124/jupyter-mcp-agent.git
cd jupyter-mcp-agent
pip install -e . # or: pip install -e ".[dev]" for tests
jupyter-mcp-agent serve --notebook /absolute/path/to/analysis.ipynbserve speaks MCP over stdio, so normally your MCP client starts it for you (see below). Use an absolute notebook path unless the client's cwd is the notebook's folder.
Claude Code
claude mcp add jupyter -- jupyter-mcp-agent serve --notebook /absolute/path/to/analysis.ipynb
# or, without installing the console script on PATH:
claude mcp add jupyter -- python -m jupyter_mcp_agent serve -n /absolute/path/to/analysis.ipynbOr commit a project-scoped .mcp.json:
{
"mcpServers": {
"jupyter": {
"command": "jupyter-mcp-agent",
"args": ["serve", "--notebook", "notebooks/analysis.ipynb", "--roots", "."]
}
}
}Claude Desktop
Add to claude_desktop_config.json (Settings > Developer > Edit Config):
{
"mcpServers": {
"jupyter": {
"command": "python",
"args": ["-m", "jupyter_mcp_agent", "serve", "-n", "C:\\path\\to\\analysis.ipynb"]
}
}
}Use the full path to the Python interpreter that has the package installed if python on PATH is a different one.
Cursor and other MCP clients
Any client that can launch a stdio MCP server works; the command is jupyter-mcp-agent serve -n <notebook> (or python -m jupyter_mcp_agent serve ...). This repo ships a project-level Cursor config in .cursor/mcp.json, plus an agent rule (.cursor/rules/research-notebook-mcp-agent.mdc) and a workflow skill (.cursor/skills/research-notebook-mcp-workflow/SKILL.md). Cursor on Windows often ignores cwd; set LLM_JUPYTER_PROCESS_CWD (or --process-cwd) when relative paths resolve in the wrong place. Reload the client after changing MCP config.
Try it without an MCP client
scripts/agent_mcp_selftest.py calls the same tool handlers in-process:
python scripts/agent_mcp_selftest.py -n examples/agent_demo_euler.ipynb --list-cell-ids
python scripts/agent_mcp_selftest.py -n examples/agent_demo_euler.ipynb run run_all=true
python scripts/agent_mcp_selftest.py notebook_validateOther CLI commands:
jupyter-mcp-agent export-apynb path/to/notebook.ipynb # (re)write the same-stem .apynb code sidecar
jupyter-mcp-agent manifest-tail path/to/notebook.ipynb --last 8 # recent manifest records for a notebook
jupyter-mcp-agent manifest-tail path/to/notebook.ipynb --run-id abcdef123456Configuration
Option / variable | Meaning |
| Default notebook; also anchors the write sandbox |
|
|
| Extra allowed directories ( |
|
|
|
|
| Dev only: restart when package sources change (needs |
| Passed into the kernel so saved figures can share a searchable prefix |
Environment variables keep the LLM_JUPYTER_ prefix, and notebooks keep the metadata.llm_jupyter namespace and the .llm_jupyter/ evidence folder, so existing notebooks and configs keep working.
Security: with --notebook set, writes are limited to that notebook's folder plus --roots. Without -n, each tool call is anchored only to the path it names, so use -n in real projects. The kernel runs arbitrary code as your user. Only point it at notebooks you trust.
Architecture
MCP client (Claude Code / Desktop / Cursor / ...)
| stdio (Model Context Protocol)
v
server.py FastMCP tool surface, JSON envelopes, path sandbox
session.py per-notebook kernel pool (jupyter_client), exclusive locks, run orchestration
notebook.py / notebook_cells_patch.py / cells_apply_helpers.py nbformat read/modify/write
manifest.py / stamp.py / env_snapshot.py run_id, file stamps, manifest.jsonl, env capture
chunks.py / previews.py / stream_artifacts.py capped stdout/stderr, previews, spill files
companion.py .apynb code-cell sidecar export and drift checks
cli.py `serve`, `export-apynb`, `manifest-tail`Source lives in src/jupyter_mcp_agent/; src/llm_jupyter/ is the compatibility alias.
Repository layout
Path | Contents |
| The package |
| pytest suite ( |
| Small demo notebooks (examples/README.md) |
| MCP vs no-MCP research notebooks (benchmarks/README.md) |
| Selftest harness, profiling and demo scripts |
| PRD and implementation notes |
Development
pip install -e ".[dev]"
pytest -qStatus
Beta (0.3.x). The MCP tool surface is usable day to day but may still change between minor versions; see CHANGELOG.md. Tested on Windows and Linux with Python 3.10 and 3.12.
License
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Build, validate, and deploy multi-agent AI solutions from any AI environment.
Run AI evaluations, record agent traces and gate releases on evidence, with scoped org access.
Pre-execution governance for AI agents. Deterministic PASS/FAIL/REVIEW verdicts, replayable proof.
Persistent cloud workspaces for AI agents: run commands, edit files, use git and a browser.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI agents to create, read, edit, and execute Jupyter notebook cells, manage kernels, and connect to remote Jupyter servers.21MIT
- AlicenseAqualityDmaintenanceEnables AI agents to execute Python, TypeScript, and JavaScript code in persistent Jupyter kernels with stateful variables and imports across interactions.74MIT
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to execute Jupyter notebook cells with persistent kernel state, output persistence, and structured JSON control surface.2-
- AlicenseAqualityDmaintenanceEnables AI assistants to read, edit, and execute Jupyter notebook files (.ipynb) with live kernel output, without requiring JupyterLab.17MIT