JupyterMCP
Allows AI agents to create, read, edit, and execute Jupyter notebook cells, manage kernels, and connect to remote Jupyter servers.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@JupyterMCP Create a notebook called analysis and run a cell that loads data.csv"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
JupyterMCP
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-serverOr with uv:
uv add mcp-jupyter-serverRelated MCP server: mcp-server-jupyter
Adding to Claude Code
Option 1 — CLI (recommended)
claude mcp add jupyter -- jupyter-mcpPin notebooks to a specific directory at startup:
claude mcp add jupyter -- jupyter-mcp --working-dir /path/to/your/notebooksOption 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.jsonWindows:
%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 |
|
Cells |
|
Kernels |
|
Workspace |
|
Remote |
|
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 loadsdata.csvwith pandas, and execute it."
"Show me
model_training.ipynbas 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:8888and 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 |
|
Environment variable |
|
At runtime |
|
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 |
|
Environment variables |
|
At runtime |
|
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: strnotebook_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: strnotebook_list
List all .ipynb files in the current working directory.
notebook_delete
Delete a notebook file and shut down its kernel if running.
name: strnotebook_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 = TrueExample 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 = appendReturns 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: strcell_delete
Delete a cell by ID.
name: str
cell_id: strcell_move
Reorder a cell within the notebook.
name: str
cell_id: str
new_position: int — 0-indexedcell_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 kernelKernels
kernel_status
Get the current status (not_started, idle, or dead) and Python interpreter of a notebook's kernel.
name: strkernel_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 restartkernel_interrupt
Send an interrupt signal to stop a long-running or stuck cell.
name: strWorkspace
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 existRemote 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: strremote_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_* toolsUses 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 syncLicense
MIT
Available Tools
21 toolscell_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_deleteADestructiveIdempotent
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_directoryARead-only
Get the current working directory for notebook operations.
Inputs: no named parameters.
kernel_interruptAIdempotent
Send an interrupt signal to the running kernel. Use this to stop a long-running or infinite-loop cell execution.
Inputs: name (required).
kernel_listARead-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_restartADestructive
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_startADestructive
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_statusARead-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_scriptARead-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_deleteADestructiveIdempotent
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_getARead-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_listARead-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_disconnectAIdempotent
Disconnect from the remote Jupyter Server and switch back to local kernels. All running remote kernels are shut down.
Inputs: no named parameters.
remote_statusARead-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
Scored across 21 tools
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.
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.
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.
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
Related MCP Connectors
Persistent cloud workspaces for AI agents: run commands, edit files, use git and a browser.
Linux VMs for AI agents: create VMs, run commands, edit files and open preview URLs.
Connect your AI agent to 300+ methods and 100+ live tools
Control a real browser from AI agents: navigate, click, type, screenshot, read the page.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables 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.446Apache 2.0
- AlicenseAqualityDmaintenanceEnables programmatic interaction with Jupyter notebooks, allowing reading, editing, and executing cells via Claude.634 PyPI34MIT
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to execute Jupyter notebook cells with persistent kernel state, output persistence, and structured JSON control surface.2-
- FlicenseNot gradedqualityDmaintenanceEnables 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-