Skip to main content
Glama

JupyterMCP

PyPI Python License: MIT

An MCP server that gives AI agents full control over Jupyter notebooks — create, read, edit, and execute cells, manage kernels, and connect to remote Jupyter Servers.

Works with Claude Code, Claude Desktop, and any other MCP-compatible client.


Installation

pip install mcp-jupyter-server

Or with uv:

uv add mcp-jupyter-server

Related MCP server: mcp-server-jupyter

Adding to Claude Code

claude mcp add jupyter -- jupyter-mcp

Pin notebooks to a specific directory at startup:

claude mcp add jupyter -- jupyter-mcp --working-dir /path/to/your/notebooks

Option 2 — Project config (.mcp.json)

{
  "mcpServers": {
    "jupyter": {
      "command": "jupyter-mcp",
      "args": ["--working-dir", "/path/to/your/notebooks"]
    }
  }
}

Option 3 — Global config (~/.claude/settings.json)

{
  "mcpServers": {
    "jupyter": {
      "command": "jupyter-mcp"
    }
  }
}

After adding, verify the connection with /mcp in Claude Code.


Adding to Claude Desktop

Edit your config file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "jupyter": {
      "command": "jupyter-mcp",
      "args": ["--working-dir", "/path/to/your/notebooks"]
    }
  }
}

Restart Claude Desktop after saving.


What You Can Do

JupyterMCP exposes 19 tools across five categories:

Category

Tools

Notebooks

notebook_create, notebook_get, notebook_list, notebook_delete, notebook_as_script, notebook_execute_all

Cells

cell_add, cell_update, cell_delete, cell_move, cell_execute

Kernels

kernel_status, kernel_restart, kernel_interrupt

Workspace

get_notebook_directory, set_notebook_directory

Remote

remote_connect, remote_disconnect, remote_status

Notebooks are always saved as .ipynb files. Kernel state (variables, imports) persists between cell executions within the same session.

Example prompts

"Create a notebook called analysis, add a cell that loads data.csv with pandas, and execute it."

"Show me model_training.ipynb as a single Python script so I can review the logic."

"Something's wrong in cell 3 of pipeline.ipynb — read the notebook, fix it, and re-run."

"Connect to my remote GPU server at http://10.0.0.5:8888 and run the training notebook there."


Configuration

Working directory

Controls where notebooks are read from and written to. Defaults to the current working directory.

Method

Example

CLI arg

--working-dir /home/user/notebooks

Environment variable

CLAUDE_CODE_CWD=/home/user/notebooks

At runtime

set_notebook_directory tool

Remote Jupyter Server

Route kernel execution to a remote Jupyter Server while keeping notebooks saved locally. Useful for cloud GPUs, remote data, or shared compute.

Method

Example

CLI args

--remote-url http://host:8888 --remote-token mytoken

Environment variables

JUPYTER_SERVER_URL=http://host:8888 / JUPYTER_SERVER_TOKEN=mytoken

At runtime

remote_connect tool

Find your Jupyter token in the server startup output:

http://localhost:8888/?token=abc123...

Tool Reference

Notebooks

notebook_create

Create a new empty notebook. The .ipynb extension is added automatically.

name: str

notebook_get

Return the full notebook structure: all cells with their IDs, types, source, execution counts, and outputs. Use the returned cell IDs with cell_update, cell_delete, cell_move, and cell_execute.

name: str

notebook_list

List all .ipynb files in the current working directory.

notebook_delete

Delete a notebook file and shut down its kernel if running.

name: str

notebook_as_script

Return the entire notebook as a single Python string using # %% cell markers (compatible with VS Code, Spyder, and nbconvert). Useful for letting an agent read and reason about a notebook as a complete program.

Code cells are pasted verbatim; markdown cells have each line prefixed with # .

name:             str
include_markdown: bool = True

Example output:

# %% [cell 0 · code · id:abc123]
import pandas as pd
df = pd.read_csv("data.csv")

# %% [cell 1 · markdown · id:def456]
# ## Data Cleaning
# Drop rows with missing values.

# %% [cell 2 · code · id:ghi789]
df = df.dropna()
df.head()

notebook_execute_all

Execute all code cells in order. Markdown and raw cells are skipped.

name:          str
timeout:       int  = 30
stop_on_error: bool = True
python_path:   str  = ""

Cells

cell_add

Add a new cell to a notebook.

name:      str
source:    str
cell_type: str = "code"   — "code", "markdown", or "raw"
position:  int = -1       — 0 = prepend, -1 = append

Returns the new cell's cell_id and position.

cell_update

Replace a cell's source. For code cells, clears existing outputs and execution count.

name:    str
cell_id: str   — from notebook_get
source:  str

cell_delete

Delete a cell by ID.

name:    str
cell_id: str

cell_move

Reorder a cell within the notebook.

name:         str
cell_id:      str
new_position: int   — 0-indexed

cell_execute

Execute a single code cell and return its outputs. Saves outputs back to the .ipynb file.

name:        str
cell_id:     str
timeout:     int = 30
python_path: str = ""   — only applies when starting a new kernel

Kernels

kernel_status

Get the current status (not_started, idle, or dead) and Python interpreter of a notebook's kernel.

name: str

kernel_restart

Restart the kernel, clearing all in-memory state. Saved cell outputs are not affected.

name:        str
python_path: str = ""   — switch to a different interpreter on restart

kernel_interrupt

Send an interrupt signal to stop a long-running or stuck cell.

name: str

Workspace

get_notebook_directory

Return the current working directory for notebook operations.

set_notebook_directory

Change the working directory. All subsequent notebook operations use the new path.

path: str   — must already exist

Remote Execution

remote_connect

Connect to a remote Jupyter Server. All kernel operations are routed there; notebooks are still saved locally.

server_url: str   — e.g. "http://hostname:8888"
token:      str

remote_disconnect

Disconnect from the remote server, shut down remote kernels, and revert to local execution.

remote_status

Show whether a remote server is connected and which URL it is using.


Architecture

src/jupyter_mcp/
├── server.py                — FastMCP server, CLI arg parsing
├── notebook_manager.py      — Read/write/serialize .ipynb files
├── kernel_manager.py        — Local kernel lifecycle
├── remote_kernel_manager.py — Remote kernel lifecycle (REST + WebSocket)
├── executor.py              — Cell execution and output collection
└── tools/
    ├── notebooks.py         — notebook_* tools
    ├── cells.py             — cell_* tools
    ├── execution.py         — cell_execute, notebook_execute_all
    ├── kernel.py            — kernel_* tools
    └── remote.py            — remote_* tools

Uses stdio transport — runs as a subprocess of the MCP client. Notebooks are standard .ipynb files and can be opened in JupyterLab, VS Code, or any Jupyter-compatible editor at any time.


Contributing

git clone https://github.com/Try3D/JupyterMCP
cd JupyterMCP
uv sync

License

MIT

Available Tools

21 tools
cell_addA

Add a new cell to a notebook.

  • name: notebook name (with or without .ipynb)

  • source: the cell content / code

  • cell_type: 'code', 'markdown', or 'raw' (default: 'code')

  • position: index to insert at (0 = first cell, -1 = append at end) Returns the new cell's ID and position.

Inputs: name (required), source (required), cell_type, position.

cell_deleteA
DestructiveIdempotent

Delete a cell from a notebook by its cell ID. Use notebook_get to find cell IDs.

Inputs: name (required), cell_id (required).

cell_executeA

Execute a specific code cell and return its output. The kernel state persists between executions (variables, imports, etc. remain in memory). Only code cells can be executed. Outputs are saved back to the .ipynb file.

python_path controls which Python interpreter runs the kernel:

  • "" or omitted: uses the server's own Python (sys.executable) the first time; subsequent calls reuse the already-running kernel regardless.

  • Absolute path: e.g. "/home/user/myproject/.venv/bin/python"

  • Name on PATH: e.g. "python3.11" Only takes effect when a new kernel is being started (no kernel running yet). Use kernel_restart to switch an already-running kernel to a different Python.

Inputs: name (required), cell_id (required), timeout, python_path.

cell_moveA

Move a cell to a new position in the notebook. new_position is 0-indexed. Use notebook_get to see current positions.

Inputs: name (required), cell_id (required), new_position (required).

cell_updateA

Update the source content of a cell. For code cells, this clears existing outputs and execution count since the code has changed. Use notebook_get to find cell IDs.

Inputs: name (required), cell_id (required), source (required).

get_notebook_directoryA
Read-only

Get the current working directory for notebook operations.

Inputs: no named parameters.

kernel_interruptA
Idempotent

Send an interrupt signal to the running kernel. Use this to stop a long-running or infinite-loop cell execution.

Inputs: name (required).

kernel_listA
Read-only

List all kernels currently tracked in this session, with their status (idle/dead) and Python interpreter path. Only kernels started during this MCP session are listed.

Inputs: no named parameters.

kernel_restartA
Destructive

Restart the kernel for a notebook. Clears all in-memory state (variables, imports, etc.). Cell outputs saved to the .ipynb file are not affected.

python_path: optionally switch to a different Python interpreter on restart.

  • "" or omitted: keep using the same Python the kernel was started with.

  • Absolute path: e.g. "/home/user/project/.venv/bin/python"

  • Name on PATH: e.g. "python3.11" If python_path differs from the current kernel's Python, the kernel is fully replaced rather than just restarted in-place.

Inputs: name (required), python_path.

kernel_startA
Destructive

Shut down any existing kernel for this notebook and start a completely fresh one. Unlike kernel_restart, this always creates a new kernel process from scratch — even if the Python interpreter is unchanged. Use this at session start to enforce a specific Python environment, or to guarantee a clean slate.

python_path: which Python to use for the new kernel.

  • "" or omitted: uses the server's own Python (sys.executable)

  • Absolute path: e.g. "/home/user/project/.venv/bin/python"

  • Name on PATH: e.g. "python3.11" Not supported when connected to a remote server (use remote_connect to select the server; the remote server controls the interpreter).

Inputs: name (required), python_path.

kernel_statusA
Read-only

Get the current status and Python interpreter of the kernel for a notebook. Status is one of: 'not_started', 'idle', or 'dead'. python_path shows which Python executable the kernel is using (null if not started).

Inputs: name (required).

notebook_as_scriptA
Read-only

Return the entire notebook as a single Python script string.

Each cell is preceded by a # %% marker (the convention used by VSCode, Spyder, and nbconvert) so the script can be analysed, diffed, or reasoned about as a complete program.

  • Code cells: source pasted verbatim under their marker.

  • Markdown cells: each line prefixed with "# " under their marker. Omitted entirely when include_markdown=False.

  • Raw cells: always skipped.

The script is returned in the response; no file is written to disk.

Inputs: name (required), include_markdown.

notebook_createA

Create a new Jupyter notebook (.ipynb) in the working directory. The .ipynb extension is added automatically if not included. Returns the notebook name and path on success.

Inputs: name (required).

notebook_deleteA
DestructiveIdempotent

Delete a notebook file and shut down its kernel if running. The .ipynb extension is optional.

Inputs: name (required).

notebook_execute_allA

Execute all code cells in the notebook in order. Markdown and raw cells are skipped. If stop_on_error is True (default), execution stops at the first cell that raises an exception. Returns a summary of results for each code cell executed.

python_path: which Python to use if no kernel is running yet (see cell_execute).

Inputs: name (required), timeout, stop_on_error, python_path.

notebook_getA
Read-only

Read a notebook and return its full structure: all cells with their IDs, types, source, execution counts, and outputs.

Use the returned cell IDs with cell_update, cell_delete, cell_move, and cell_execute to modify or run specific cells.

Inputs: name (required).

notebook_listA
Read-only

List all .ipynb notebooks in the working directory.

Inputs: no named parameters.

remote_connectA

Connect to a remote Jupyter Server and route all kernel operations to it. Notebooks continue to be saved locally; only code execution runs on the remote kernel. Useful for accessing remote compute, GPUs, or data.

server_url: Base URL of the remote Jupyter Server, e.g. "http://hostname:8888" token: API token (the value printed by Jupyter on startup, or set via --NotebookApp.token / --ServerApp.token)

Any currently running remote kernels are shut down before switching.

Inputs: server_url (required), token (required).

remote_disconnectA
Idempotent

Disconnect from the remote Jupyter Server and switch back to local kernels. All running remote kernels are shut down.

Inputs: no named parameters.

remote_statusA
Read-only

Show whether a remote Jupyter Server is connected and which URL it is using.

Inputs: no named parameters.

set_notebook_directoryC

Set the working directory for notebook operations. All subsequent notebook operations will use this directory. Useful for specifying where notebooks should be saved and loaded from.

Inputs: path (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 21 tools

    Disambiguation5/5

    Each tool targets a distinct action or resource: cell, kernel, notebook, remote, or directory. The kernel-related tools are clearly differentiated (interrupt vs restart vs start), and similarly for cells and notebooks. There is no functional overlap that could confuse an agent.

    Naming Consistency5/5

    All tool names follow a consistent 'resource_verb' pattern: e.g., cell_add, kernel_restart, notebook_get, remote_connect, set_notebook_directory. The naming is uniform and predictable, making it easy for an agent to infer tool purposes.

    Tool Count4/5

    With 21 tools, the set is comprehensive but not excessive. The number is appropriate given the need to cover notebook CRUD, cell manipulation, kernel management, remote connectivity, and directory handling. It is slightly on the high side but remains well-scoped.

    Completeness5/5

    The tool surface covers all essential notebook operations: create/read/update/delete for notebooks and cells, execution (single cell and whole notebook), kernel lifecycle (start, restart, interrupt, status, list), remote server connection for execution, and workspace directory management. There are no obvious gaps.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables AI agents to interact with Jupyter notebooks via MCP tools for querying, modifying, executing, and setting up notebooks, with state preservation and real-time collaboration.
      4
      46
      Apache 2.0
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to execute Jupyter notebook cells with persistent kernel state, output persistence, and structured JSON control surface.
      2
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to safely and structurally edit Jupyter Notebook (.ipynb) files by providing tools to read, edit, add, and delete cells without corrupting the JSON structure.
      1
      -