mcp-jupyter-server 0.1.1

MCP server that gives AI agents full control over Jupyter notebooks

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-server

Or with uv:

uv add mcp-jupyter-server

---

Adding to Claude Code

Option 1 — CLI (recommended)

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