Jupyter MCP Server

🚀 Jupyter_MCP_Server

JupyterMCP integrates Jupyter Notebook with Claude AI via the Model Context Protocol (MCP), enabling Claude to directly interact with and control Jupyter notebooks. This integration facilitates AI-assisted code execution, data analysis, visualization, and more.

🚀 Quick Start

Prerequisites

• Python 3.12 or higher (It may be compatible with older versions, but it hasn't been tested).
• [uv package manager](/README.md#Installation of uv)
• Claude AI desktop application

Installation of uv

If you're using a Mac:

brew install uv

On Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

For other platforms, refer to the uv installation guide.

Setup

1. Clone or download this repository to your computer:

git clone https://github.com/jjsantos01/jupyter-notebook-mcp.git

2. Create a virtual environment, install the required packages, and install the jupyter-mcp kernel so that it can be recognized by the Jupyter installer:

uv run python -m ipykernel install --name jupyter-mcp

3. (Optional) Install additional Python packages for data analysis:

uv pip install seaborn

4. Configure the Claude desktop integration: Go to Claude > Settings > Developer > Edit Configuration > claude_desktop_config.json and include the following content:

{
    "mcpServers": {
        "jupyter": {
            "command": "uv",
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/PARENT/REPO/FOLDER/src",
                "run",
                "jupyter_mcp_server.py"
            ]
        }
    }
}

Replace /ABSOLUTE/PATH/TO/ with the actual path. For example:

• On Windows: "C:\\Users\\MyUser\\GitHub\\jupyter-notebook-mcp\\src\\"
• On Mac: /Users/MyUser/GitHub/jupyter-notebook-mcp/src/ If you had previously opened Claude, close it and reopen it.

Starting the Connection

1. Start your Jupyter Notebook (version 6.x) server:

uv run jupyter notebook

2. Open your browser and navigate to http://localhost:8888, then go to the jupyter_mcp_server.py notebook.
3. Execute the following code in the notebook to start the MCP server:

from jupyter_mcp_server import start_server
start_server()

✨ Features

• Bidirectional Communication: Connects Claude AI to Jupyter Notebook via a WebSocket-based server.
• Cell Operations: Insert, execute, and manage cells in the notebook.
• Notebook Management: Save notebooks and retrieve notebook information.
• Cell Execution: Execute specific cells or run all cells in the entire notebook.
• Output Retrieval: Get the output content of executed cells, with an option for text limits.

📦 Installation

The installation process has been detailed in the "Quick Start" section above.

💻 Usage Examples

Basic Usage

After establishing the connection, Claude will have access to the following tools:

# For example, check server connectivity
ping()

# Insert and execute a cell at a specified position
insert_and_execute_cell()

# Save the current Jupyter notebook
save_notebook()

# Get information about all cells
get_cells_info()

# Get information about the current notebook
get_notebook_info()

# Run a specific cell by index
run_cell()

# Run all cells in the notebook
run_all_cells()

# Get the text output of a specific cell
get_cell_text_output()

# Get the image output of a specific cell
get_image_output()

# Edit the content of an existing cell
edit_cell_content()

# Set the slide type of a cell
set_slideshow_type()

🔧 Technical Details

The system consists of three main components:

1. WebSocket Server (jupyter_ws_server.py): Sets up a WebSocket server in Jupyter to enable communication between the notebook and external clients.
2. Client JavaScript (client.js): Runs within the notebook to handle operations such as inserting cells and executing code.
3. MCP Server (jupyter_mcp_server.py): Implements the Model Context Protocol and connects to the WebSocket server.