home / mcp / jupyter mcp server

Jupyter MCP Server

Exposes notebook management actions such as reading, adding, editing, and executing notebook cells via MCP tools.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "ihrpr-mcp-server-jupyter": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-server-jupyter",
        "mcp-server-jupyter"
      ],
      "env": {
        "UV_PROJECT_ENVIRONMENT": "<path-to-venv>"
      }
    }
  }
}

You can manage and interact with Jupyter notebooks programmatically using this MCP server. It exposes a set of notebook-focused tools and integrates with your existing Jupyter setup, allowing you to read, create, edit, and execute notebook cells from an MCP client.

How to use

You configure an MCP client to connect to the Jupyter notebook manager server and then call the available tools to perform operations on notebooks. The server uses a standard input/output (stdio) approach when run via the UV tool, so you will start the MCP server through a command that forwards requests to the notebook manager. After you call a tool, reload your notebook page if needed to reflect changes.

How to install

Prerequisites you need before you start: a working Python environment and Node-compatible tooling, plus the ability to install JupyterLab in a virtual environment.

Steps to set up your environment and run the MCP server:

uv venv --seed
source .venv/bin/activate
uv pip install jupyterlab
.venv/bin/jupyter lab
```

Note: this environment path is used as UV_PROJECT_ENVIRONMENT in the MCP server configuration. You can verify the path by printing the current working directory and appending .venv as shown in the guidance.

Additional configuration and usage notes

To connect Claude Desktop with the Jupyter notebook manager, configure an MCP server entry that runs under UV. The configuration uses the UV tool to run the MCP server with your Jupyter notebook manager module.

{
  "mcpServers": {
    "jupyter_mcp": {
      "command": "uv",
      "args": ["run", "--with", "mcp-server-jupyter", "mcp-server-jupyter"],
      "env": {
        "UV_PROJECT_ENVIRONMENT": "/path/to/venv_for_jupyter/.venv"
      }
    }
  }
}

Important notes

After any modifications through the MCP client (such as add_cell or edit_cell), reload the notebook page in JupyterLab or Jupyter Notebook to see the changes, as automatic reload is not yet supported in this setup.

Tools you can use

The server provides six tools to interact with notebooks and cells.

Security and maintenance

Keep your Jupyter server and MCP components up to date. Run the integration in a controlled environment and avoid exposing the MCP endpoint to untrusted networks. Regularly review the environment variables and permissions used by the MCP server.

Available tools

read_notebook_with_outputs

Read a notebook's content including all cell outputs. Requires notebook_path as input.

read_notebook_source_only

Read notebook content without outputs. Use when size limits prevent reading full notebook with outputs. Requires notebook_path.

read_output_of_cell

Read the output of a specific cell. Requires notebook_path and cell_id.

add_cell

Add a new cell to a notebook. Requires notebook_path and source. Optional: cell_type (code or markdown) and position (insertion index, -1 to append).

edit_cell

Modify the content of an existing cell. Requires notebook_path, cell_id, and new source.

execute_cell

Execute a specific cell and return its output. Requires notebook_path and cell_id.