Jupyter

Jupyter MCP Server connects and manages Jupyter Notebooks through the Model Context Protocol (MCP), enabling AI systems to orchestrate multiple notebooks, run interactive tasks, and produce multi-modal outputs such as text, images, and tables. It is designed to empower AI IDEs and CLI tools to control and collaborate with Jupyter Kernel and notebooks efficiently.

How to use

You will connect an MCP client to a local or remote MCP server exposed for Jupyter Notebook management. Use the MCP client to list connected notebooks, connect or create new notebooks, and execute cells across multiple notebooks. Take advantage of multi-modal outputs to receive results as text, images, and tables. Use structured prompts and task decomposition to split complex workflows into smaller steps (data cleaning, feature engineering, model training, evaluation, etc.). Ensure your client supports MCP and handles multi-notebook orchestration for best performance.

Typical usage pattern includes: connect to or create notebooks, inspect cells, insert or modify cells, execute cells, and iterate based on outputs. When working with multiple notebooks, you can target specific notebooks by name, manage their cells, and coordinate cross-notebook analysis. For best results, provide clear prompts with context about dataset schemas, file paths, and the goals of each notebook task.

How to install

Prerequisites you need before installing the server:

• Python 3.12 or newer (recommended via Anaconda)

• A runtime environment capable of executing MCP client configurations (the MCP-compatible client will connect to this server)

Step by step installation and setup options follow. Choose the approach that matches your environment.

# Quick start with uvx (recommended)
{
  "mcpServers":{
    "Jupyter-MCP-Server":{
      "command": "uvx",
      "args": [
        "better-jupyter-mcp-server"
      ],
      "env": {
        "ALLOW_IMG": "true"
      },
      "transport": "stdio"
    }
  }
}

Alternative JSON configuration example for a local setup using uv to run a specified path and script:

{
  "mcpServers":{
    "Jupyter-MCP-Server":{
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "your/path/to/jupyter-mcp-server",
        "src/main.py"
      ],
      "env": {},
      "transport": "stdio"
    }
  }
}

Additional sections

Starting the MCP server locally requires running the appropriate command through your chosen MCP launcher. A typical startup sequence shows the successful launch message indicating the server name and transport is active.

To run the server directly using uvx, you would typically start the MCP process and then verify the startup output, ensuring the transport is stdio and the server name matches your configuration.

Notes on configuration and usage

Keep in mind that the server is designed to manage multiple notebooks. When crafting prompts for the AI, include contextual details such as dataset descriptions, file paths, and notebook names to improve routing and execution efficiency. If you enable image or rich outputs, ensure the MCP client you use can parse and render those outputs.

Troubleshooting

If the server fails to start, verify that the specified command and arguments are correct, and that the required dependencies are installed in your environment. Check that the transport is set to stdio if you expect to communicate via standard input/output. Ensure that environment variables needed by the server are provided in the configuration.

Available tools

connect_notebook

Connect or create a notebook at a specified path, establishing a session for management.

list_notebook

List all currently connected notebooks to monitor active sessions.

restart_notebook

Restart a specified notebook, clearing imports and variables to reset the state.

read_notebook

Read the source content of a notebook without including execution outputs.

list_cell

List basic information for all cells in a given notebook to identify indices.

read_cell

Read the content of a specific cell, supporting outputs like images, tables, or text.

delete_cell

Delete a specified cell from a notebook.

insert_cell

Insert a new cell at a given position relative to a target cell in a notebook.

execute_cell

Execute a specific cell and return its output.

overwrite_cell

Overwrite the content of a specific cell in a notebook.

append_execute_code_cell

Append a code cell to the end of the notebook and execute it in one operation.

execute_temporary_code

Run a temporary code block without storing it in the notebook for quick experimentation.