JupyMCP

JupyMCP is a local-first Model Context Protocol server for editing and executing Jupyter notebooks. It starts and manages kernels itself, so a separate Jupyter Server, URL, or token is not required.

Quick start

Configure an MCP client to launch JupyMCP over stdio:

{
  "mcpServers": {
    "jupymcp": {
      "command": "uvx",
      "args": ["jupymcp", "--workspace-root", "/path/to/project"]
    }
  }
}

All notebook paths passed to tools are relative to --workspace-root, which defaults to the process working directory. Absolute paths and paths that escape this root are rejected.

Tools

Cell operations that target an existing cell require exactly one of cell_id or index. IDs remain stable across source edits, metadata changes, moves, and execution.

Mutation tools accept an optional expected_revision. Obtain it with get_notebook_revision; if the file changes before the atomic replace, the mutation fails with a revision conflict instead of overwriting the newer file. execute_cell always applies this check internally across the execution window. JSON-lines open responses include revision, which clients should return in save.params.revision.

execute(type="py:percent") persists cells as a Jupytext percent script with # %% markers. The script format stores source and metadata, but not rich execution outputs.

Resources

Transports

Execution is bounded by server-wide defaults: 120 seconds per call (maximum requested timeout 3600 seconds), 1 MiB or 128 captured output blocks, 8 managed kernels, and 15 minutes of notebook-session idle time. Configure these with --default-timeout, --max-timeout, --max-output-bytes, --max-output-blocks, --max-kernels, and --idle-timeout. Output overflow is persisted and returned with an explicit truncation marker; increase limits deliberately for unusually large results.

HTTP transports bind only to 127.0.0.1 and enable Host/Origin validation plus DNS-rebinding protection. They do not yet provide user authentication, so do not expose them through a reverse proxy or public network.

Security model

JupyMCP deliberately provides arbitrary code execution through Jupyter kernels. Run it only for trusted MCP clients and use a dedicated --workspace-root. The workspace boundary limits notebook file access; it is not a process sandbox, and executed code retains the permissions of the JupyMCP process.

Notebook sessions get separate kernels by default. Repeated execution in the same notebook preserves state, while different notebooks do not share variables unless the caller explicitly supplies the same kernel_id.

When neither kernel_id nor kernel_name is supplied, JupyMCP uses the existing notebook's metadata.kernelspec.name before falling back to the system default. Notebook-session controls affect only the normalized notebook path; a deliberately shared kernel remains alive until its final notebook binding is released.

Local Jupyter kernel messaging can use unencrypted loopback TCP depending on the installed kernelspec and jupyter_client configuration. Do not expose kernel connection files or ports to untrusted users.

Development

uv sync --dev
uv run pytest --cov=src/jupymcp
uv run ruff check .
uv run ruff format --check .
uv build

Generated notebook schema models live in src/jupymcp/model.py; regenerate them with uv run python scripts/generate-model.py instead of editing that file manually.

Alternatives

• jupyter-mcp-server
• jupyter-mcp
• mcp-jupyter

JupyMCP focuses on a lightweight local workflow that does not require an already-running Jupyter Server.