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.

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

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.

Get the current working directory for notebook operations.

List all .ipynb notebooks in the working directory.

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.

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.

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.

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

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.

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

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.

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).

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.

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

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).

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).

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.

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.

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

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