JupyterMCP Server

JupyterMCP is an MCP server that lets you remotely control and automate Jupyter notebooks using a dedicated MCP interface. With this server, you can open notebooks, run specific cells, insert or edit content, inspect notebook structure, and save or export results, all through a simple programmatic API.

How to use

You connect to the JupyterMCP server from an MCP client and issue commands to manage notebooks and cells. Common workflows include opening or creating a notebook, inserting new cells, executing single or multiple cells, retrieving outputs, and saving the notebook state. You can also configure slides mode for presentations and fetch structured information about the notebook and its cells.

A typical usage pattern looks like: open a notebook, insert a new code cell, write code, execute the cell, review the output, and save the notebook. You can also request information about all cells or the notebook’s basic metadata to build dynamic UI or automation routines.

How to install

Prerequisites you need before installing are Python 3.10 or later and either Jupyter Notebook or JupyterLab installed on your system.

Install and run the JupyterMCP server by following these steps in your terminal.

# Clone the project repository
git clone https://github.com/maskperson114514/jupyterMCP.git
cd jupyterMCP

# Install dependencies
pip install -r requirements.txt

# Start the MCP server
python jupyterMCP.py --host 127.0.0.1 --port 48080

Configuration and usage notes

Configure your MCP client to connect to the server via the SSE URL and enable the actions you want to perform on notebooks and cells. The following client configuration demonstrates enabling common actions and pointing to the local server over SSE.

{
  "mcpServers": {
    "jupyterMCP": {
      "autoApprove": [
        "save_notebook",
        "get_cells_info",
        "insert_and_execute_cell",
        "run_cell",
        "edit_cell_content",
        "execute_cells_by_indices",
        "run_all_cells",
        "get_notebook_info",
        "get_cell_text_output",
        "set_slideshow_type"
      ],
      "timeout": 60,
      "url": "http://localhost:48080/sse",
      "transportType": "sse"
    }
  }
}

Server start and endpoints

To run the server locally, start the Python script with the host and port you want to listen on. The example below binds to localhost on port 48080.

python jupyterMCP.py --host 127.0.0.1 --port 48080

Technical details

The server exposes an HTTP-based MCP endpoint at the configured URL for remote interaction. Clients use the SSE transport type to receive streaming updates and responses from operations such as opening notebooks, executing cells, and retrieving outputs. Use the provided client configuration to authorize and control which actions are automatically approved by default.

API functions and capabilities

The JupyterMCP server provides a set of core functions you can call from your MCP client to manage notebooks and cells.

Security considerations

Limit access to the MCP endpoint to trusted clients and use authentication if available. Keep the server behind a secured network and consider enabling TLS/HTTPS if you expose the endpoint beyond a trusted environment.

Troubleshooting

If the server fails to start, confirm that Python 3.10+ is installed, dependencies are installed from requirements.txt, and the chosen host/port are not in use by another process. Check that the URL in client configurations matches the running server and that SSE transport is available on the server.

Available tools

open_notebook

Opens an existing notebook or creates a new one if it does not exist. Returns the notebook reference and basic metadata.

run_cell

Executes a single cell by its index within the active notebook and returns execution results.

execute_cells_by_indices

Executes multiple cells in the specified order by their indices and aggregates outputs.

save_notebook

Saves the current state of the notebook to disk, preserving all cell contents and outputs.

insert_and_execute_cell

Inserts a new cell at a specified position, fills it with code, and immediately executes it.

insert_cell

Inserts a new empty cell at a specified position without executing it.

get_cells_info

Retrieves information about all cells in the current notebook, including type, content, and outputs.

get_notebook_info

Fetches basic metadata about the notebook, such as name, path, and structure.

run_all_cells

Executes all code cells in the notebook in sequence and collects the complete output.

get_cell_text_output

Returns the textual output produced by a specific cell.

edit_cell_content

Edits the content of a specified cell and applies changes to the notebook.

set_slideshow_type

Sets the slideshow type for a cell to enable presentation mode.

delete_cell

Removes a specified cell from the notebook.