Jupyter Notebook MCP

🚀 Usage Guide

This guide provides a comprehensive overview of how to install, configure, and use the system, including steps for setting up dependencies, starting servers, using Claude Desktop, testing with external clients, troubleshooting, and understanding limitations.

🚀 Quick Start

Prerequisites

Ensure you have the following software installed:

• Python 3.x
• pip (for managing Python packages)
• uvicorn (for starting the WebSocket server)

Installation Steps

📦 Installation

Install the necessary dependencies by running the following command in your terminal or command prompt:

pip install uvicorn websockets jupyter-client python-dotenv

Start Jupyter Notebook

Launch Jupyter Notebook in your terminal or command prompt:

jupyter notebook

Start the WebSocket Server

Navigate to your project directory and start the WebSocket server with the following command:

uvicorn server:app --reload

This will start a local server at http://localhost:8000.

💻 Usage Examples

Using Claude Desktop

Download and Install

Visit the official link to download and install Claude Desktop.

Configure Claude Desktop

Open Claude Desktop and access the settings menu:

1. Locate API Settings.
2. Enter your API key (if available).
3. Click Save.

Connect to Jupyter Notebook

In Claude Desktop, select File > Open and choose your Jupyter Notebook file.

Testing with an External Client

Start the External Client

Run the following command to start the external client:

uv run python src/jupyter_ws_external_client.py

Batch Mode

To run in batch mode, use the following command:

uv run python src/jupyter_ws_external_client.py --batch

📚 Documentation

Troubleshooting

Connection Issues

If you experience connection timeouts, try the following steps:

• Restart the WebSocket server.
• Check for port conflicts: The default port is 8765. If it's occupied, the server will automatically select another available port.

Cell Execution Issues

Ensure that your cell content is valid and the kernel is running. You can verify this by:

1. Clicking on the Kernel menu in Jupyter Notebook.
2. Ensuring that the selected kernel is started.

WebSocket Port Conflicts

If the default port 8765 is occupied, the server will automatically attempt to use another available port.

Limitations and Notes

• Only supports Jupyter Notebook version 6.x.
• Text output is limited to 1500 characters.
• Does not support advanced Jupyter plugin interactions (e.g., custom widgets).
• Connections may time out due to extended periods of inactivity.

Additional Resources

This project was inspired by the following projects:

• ihrpr
• Datalayer