jjsantos01/jupyter-notebook-mcp

JupyterMCP connects Jupyter Notebook to Claude AI through the Model Context Protocol (MCP), allowing Claude to directly interact with and control Jupyter Notebooks. This integration enables AI-assisted code execution, data analysis, visualization, and more.
⚠️ Compatibility Warning
**This tool is compatible ONLY with Jupyter Notebook version 6.x.**
It does NOT work with:
- Jupyter Lab
- Jupyter Notebook v7.x
- VS Code Notebooks
- Google Colab
- Any other notebook interfaces
Features
- **Two-way communication**: Connect Claude AI to Jupyter Notebook through a WebSocket-based server
- **Cell manipulation**: Insert, execute, and manage notebook cells
- **Notebook management**: Save notebooks and retrieve notebook information
- **Cell execution**: Run specific cells or execute all cells in a notebook
- **Output retrieval**: Get output content from executed cells with text limitation options
Components
The system consists of three main components:
1. **WebSocket Server (jupyter_ws_server.py)**: Sets up a WebSocket server inside Jupyter that bridges communication between notebook and external clients
2. **Client JavaScript (client.js)**: Runs in the notebook to handle operations (inserting cells, executing code, etc.)
3. **MCP Server (jupyter_mcp_server.py)**: Implements the Model Context Protocol and connects to the WebSocket server
Installation
Prerequisites
- Python 3.12 or newer (probably also work with older versions, but not tested)
- uv package manager
- Claude AI desktop application
Installing uv
If you're on Mac:
On Windows (PowerShell):
For other platforms, see the uv installation guide.
Setup
1. Clone or download this repository to your computer:
2. Create virtual environment with required packages an install jupyter-mcp kernel, so it can be recognized by your jupyter installation, if you had one before.
3. (optional) Install additional Python packages for your analysis:
4. Configure Claude desktop integration:
Go to Claude > Settings > Developer > Edit Config > claude_desktop_config.json to include the following:
Replace /ABSOLUTE/PATH/TO/ with the actual path to the src folder on your system. For example:
- Windows: "C:\\Users\\MyUser\\GitHub\\jupyter-notebook-mcp\\src\\"
- Mac: /Users/MyUser/GitHub/jupyter-notebook-mcp/src/
If you had previously opened Claude, then File > Exit and open it again.
Usage
Starting the Connection
1. Start your Jupyter Notebook (version 6.x) server:
2. Create a new Jupyter Notebook and make sure that you choose the jupyter-mcp kernel: kernel -> change kernel -> jupyter-mcp
3. In a notebook cell, run the following code to initialize the WebSocket server:
Don't forget to replace here '/path/to/jupyter-notebook-mcp/src' with src folder on your system. For example:
- Windows: "C:\\Users\\MyUser\\GitHub\\jupyter-notebook-mcp\\src\\"
- Mac: /Users/MyUser/GitHub/jupyter-notebook-mcp/src/
4. Launch Claude desktop with MCP enabled.
Using with Claude
Once connected, Claude will have access to the following tools:
- ping - Check server connectivity
- insert_and_execute_cell - Insert a cell at the specified position and execute it
- save_notebook - Save the current Jupyter notebook