jupyter-notebook

JupyterMCP bridges Claude AI with a Jupyter Notebook (v6.x) running locally. Through a small WebSocket-based MCP server embedded in your Jupyter setup, Claude can inspect, modify, execute, and retrieve information from your notebook. The tool exposes a set of capabilities such as inserting and executing cells, saving notebooks, querying cell information, and obtaining outputs (including images) from cells. To use it, start the MCP integration within your Jupyter environment and ensure Claude is configured to connect to the WebSocket server exposed by jupyter_mcp_server.py. Once connected, Claude gains access to tools like insert_and_execute_cell, save_notebook, get_cells_info, get_notebook_info, run_cell, run_all_cells, get_cell_text_output, get_image_output, edit_cell_content, and set_slideshow_type, enabling end-to-end notebook manipulation from natural language requests.

Prerequisites

• Python 3.12 or newer
• uv package manager
• Claude AI desktop application

Install uv (macOS):

brew install uv

Install uv (Windows):

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

Consult the uv installation guide for other platforms if needed.

Setup and installation steps

1. Clone the repository or download the project files

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

2. Ensure uv is available and configure a Python environment

# Create and activate a virtual environment (optional but recommended)
python -m venv venv
# On Windows:
venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate

# Install required Python packages if needed (example placeholder)
pip install -r requirements.txt 2>/dev/null || true

3. Install the Jupyter MCP kernel so the notebook recognizes the integration (inside uv context)

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

4. Start the MCP server inside Jupyter by running the provided Python script path via uv

uv run jupyter nbclassic

5. Configure Claude to connect to the MCP server (see below for example configuration).

Claude configuration example Edit Claude's local config to include the MCP server entry, pointing to the uv command and the script:

{
  "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 to the src folder in your environment. If Claude was previously open, restart it to apply changes.

Compatibility: This MCP server works only with Jupyter Notebook version 6.x. It does not support Jupyter Lab, Jupyter Notebook v7.x, VS Code Notebooks, Google Colab, or other notebook interfaces. The integration runs arbitrary Python code on your machine; use caution and back up important notebooks before enabling Claude control. Ensure the Jupyter Notebook is running with the jupyter-mcp kernel (as listed in the setup steps). If you need to adjust paths in the configuration, prefer absolute paths to avoid runtime lookup issues. When starting the WebSocket server inside Jupyter, verify that your firewall allows local WebSocket communication between Claude and the Jupyter process.