Jupyter MCP Server Kshitij

🚀 Jupyter MCP Server Client

This repository contains a Docker-based client for connecting to a Jupyter server that supports multi-collaboration protocols. It is suitable for use on Windows and Mac in the Claude desktop environment.

🚀 Quick Start

✨ Features

• A Docker-based client for connecting to a Jupyter server supporting multi-collaboration protocols.
• Compatible with Windows and Mac in the Claude desktop environment.

📦 Installation

Prerequisites

• Python 3.12.10
• Docker
• Git

Installation Steps

1. Set up the Python environment

# Create and activate a virtual environment
python3.12 -m venv env
source env/bin/activate  # Windows: env\Scripts\activate

# Install the package manager
pip install uv

# Install the required packages
uv pip install jupyterlab jupyter-collaboration ipykernel pycrdt
uv pip install jupyter-nbmodel-client jupyter_kernel_client

# Fix dependencies (compatibility requirements)
pip uninstall -y jupyter_server_ydoc pycrdt
uv pip install jupyter_server_ydoc pycrdt

2. Create your notebook

# Clone the repository -> This step is mandatory
git clone https://github.com/kshitijdesai99/jupyter_mcp_server_kshitij.git
cd jupyter_mcp_server_kshitij
touch notebook.ipynb

3. Start the Jupyter server

jupyter lab --port 8888 --IdentityProvider.token MY_TOKEN --ip 0.0.0.0

⚠️ Important Note

Replace MY_TOKEN with your preferred authentication token, or keep it as it is.

4. If you encounter the tornado.websocket.WebSocketClosedError error (for Mac)

• Delete the notebook.ipynb file.
• Create a new notebook in the Jupyter server and rename it to notebook.ipynb.

Docker Instructions

Build the Docker image

docker build -t notebook-client .

Run the client container --> Only for testing, not required for MCP

docker run \
  -e NOTEBOOK_PATH="notebook.ipynb" \
  -e SERVER_URL="http://host.docker.internal:8888" \
  -e TOKEN="MY_TOKEN" \
  notebook-client

⚠️ Important Note

When running from a different directory, use the full path to your notebook file.

Claude Desktop Integration

Add this configuration to your Claude desktop config.json file:

"jupyter": {
    "command": "docker",
    "args": [
      "run",
      "--rm",
      "-i",
      "-e", "NOTEBOOK_PATH=notebook.ipynb",
      "-e", "SERVER_URL=http://host.docker.internal:8888",
      "-e", "TOKEN=MY_TOKEN",
      "notebook-client"
    ]
}

⚠️ Important Note

There is no need to update the notebook path.

Troubleshooting

• Ensure that the Jupyter server is running before connecting the client.
• Verify that the tokens in the server and client configurations match.
• For Windows paths in Docker, use double backslashes as shown in the example.