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

Notebook resource URIs use an empty authority and an RFC 3986 path. Directory slashes remain separators while spaces, Unicode, and reserved characters are UTF-8 percent-encoded. For example, nested folder/分析.ipynb is notebook:///nested%20folder/%E5%88%86%E6%9E%90.ipynb. URI decoding is reversible; absolute paths, any .. component, malformed encodings, and paths that resolve outside the workspace are rejected before file access.

jupymcp://capabilities has a stable schema_version: "1.0" object schema. It reports output_schema_version, server name/version, the effective limits, notebook_formats, active and supported transport modes, sessions, cancellation, and sorted kernelspecs. Timeout and idle values are seconds. The advertised MCP request cancellation stops the server request; it does not automatically interrupt code already running in a kernel. Use interrupt_kernel or interrupt_notebook_session for that explicit action. JSON-lines requests do not support in-flight cancellation.

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.

execute and execute_cell publish output schema 1.0 and return an MCP CallToolResult. Rich, human-readable output remains in content; clients should read the following machine contract from structuredContent:

{
  "schema_version": "1.0",
  "execution_count": 1,
  "truncation": {
    "truncated": false,
    "omitted_blocks": 0,
    "omitted_bytes": 0
  },
  "error": null,
  "user_expressions": null
}

omitted_blocks counts complete captured output payloads omitted by the block or byte limit, including a requested user-expressions payload. omitted_bytes is exact: it sums each omitted payload's compact UTF-8 JSON size and any byte difference when an error block is normalized. Truncation no longer inserts a synthetic stderr stream, so clients cannot confuse a server limit with notebook stderr.

Kernel failures return isError: true and populate error with normalized ename, evalue, and traceback; the failed cell and bounded error output are still persisted for file-backed execution. ename is limited to 128 characters. evalue and at most four traceback lines are limited according to max_output_bytes (32–1024 characters per field, shrinking further if needed to fit). Human-readable error text in content supplements these fields and does not replace them.

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
uv run python scripts/check_distribution_contents.py dist/*

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.