npx mcpbar@latest install itisaevalex/jupyter-mcp-server-extended -c claude

npx mcpbar@latest edit -c claude

{
  "mcpServers": {
    "Jupyter MCP Extended": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "SERVER_URL",
        "-e",
        "TOKEN",
        "-e",
        "NOTEBOOK_PATH",
        "-e",
        "LOG_LEVEL=INFO",
        "jupyter-mcp-server:latest"
      ],
      "env": {
        "SERVER_URL": "http://host.docker.internal:8888",
        "TOKEN": "YOUR_SECURE_TOKEN",
        "NOTEBOOK_PATH": "notebook.ipynb"
      }
    }
  }
}

Jupyter MCP Extended

Enhanced Jupyter Notebook interaction via the Model Context Protocol

This project provides a Model Context Protocol (MCP) server that enables rich, interactive communication between AI models (like Claude) or other MCP clients and live Jupyter notebooks running in JupyterLab.

Features

• Connects MCP clients (e.g., Claude Desktop) to a running JupyterLab instance.
• Provides a wide array of tools for notebook interaction, including:
  • Cell Management: Add, delete, move, split, edit source.
  • Execution: Execute specific cells or all cells, retrieve output.
  • File System: List directory contents, get file content (with image resizing).
  • Kernel Introspection: List kernel variables, list installed packages.
  • Package Management: Install packages into the kernel environment.
  • Notebook State: Search cells, get all cell info/outputs, set target notebook path.

Requirements

• Python: >= 3.10 recommended. Using a dedicated environment manager like Conda/Miniconda is strongly advised (see Setup).
• JupyterLab: A running JupyterLab instance.
• Jupyter Collaboration Extension: Specifically version jupyter_collaboration==2.0.1.
• datalayer_pycrdt: Required dependency.
• Docker: Required to build and run the MCP server container (which includes necessary patches).
• Pillow: Required by the server (included in Docker build) for image handling.
• An MCP Client: Such as Claude Desktop.

Installation and Setup

Follow these steps carefully to create a stable environment based on debugging outcomes:

1. Create a Dedicated Conda Environment (Recommended):

Open your terminal (Anaconda Prompt or similar). Running the terminal "As Administrator" might be necessary for initial pip installs if conda base permissions are restricted on your system, although using a dedicated environment usually avoids this.

# Create a clean environment (Python 3.10 worked during debugging)
conda create -n jupyter_mcp_env python=3.10 -y

# Activate the environment
conda activate jupyter_mcp_env

Remember to activate this environment (conda activate jupyter_mcp_env) in any terminal before running pip or jupyter lab commands for this project.

2. Install Core Jupyter Components:

# Use 'python -m pip' to ensure correct pip in the activated env
python -m pip install jupyterlab ipykernel

3. Install Specific jupyter_collaboration Version:

Newer versions caused issues during debugging. Version 2.0.1 is required.

# Install the required v2.0.1
python -m pip install "jupyter_collaboration==2.0.1"

4. Handle pycrdt Dependencies:

Follow the specific uninstall/reinstall sequence:

# Uninstall potentially conflicting versions
python -m pip uninstall -y pycrdt datalayer_pycrdt

# Install the required version
python -m pip install datalayer_pycrdt

5. Enable the Collaboration Extension:

Ensure the extension is enabled within your environment:

jupyter server extension enable jupyter_collaboration --py --sys-prefix

6. Build the Patched Docker Image:

The included Dockerfile contains patches identified during debugging. Build the image locally:

# Navigate to the directory containing the Dockerfile
# cd /path/to/your/jupyter-mcp-server/
docker build -t jupyter-mcp-server:latest .

7. Start JupyterLab:

Make sure your jupyter_mcp_env conda environment is activated.

# Use a strong, unique token!
# --ip=0.0.0.0 allows the Docker container to connect
jupyter lab --port 8888 --IdentityProvider.token YOUR_SECURE_TOKEN --ip 0.0.0.0

• Security: Replace YOUR_SECURE_TOKEN with a strong, unique password or token. Do not use weak tokens.
• Windows Terminal: If using Windows Terminal/Command Prompt, ensure "QuickEdit Mode" is disabled for the terminal window running Jupyter Lab to prevent connection hangs (Right-click title bar -> Properties -> Options -> Untick QuickEdit Mode).
• Firewall: Ensure your OS firewall allows incoming connections on port 8888, especially from Docker's network interface.

Configuration

The MCP server (running in Docker) reads its configuration from environment variables passed via the MCP client configuration (e.g., claude_desktop_config.json). Key variables:

• SERVER_URL: URL of your running JupyterLab (e.g., http://host.docker.internal:8888 for Docker Desktop Win/Mac, http://localhost:8888 for Linux with --network=host). Do not include the token here.
• TOKEN: The exact token used with --IdentityProvider.token for JupyterLab.
• NOTEBOOK_PATH: Initial target notebook path relative to JupyterLab's start directory (e.g., notebook.ipynb). Changeable via the set_target_notebook tool.
• LOG_LEVEL: Server logging verbosity (DEBUG, INFO, WARNING). Default: INFO.
• OUTPUT_WAIT_DELAY: Default wait time (seconds) for get_cell_output. Default: 0.5.

Usage with Claude Desktop

1. Install Claude Desktop.
2. Locate claude_desktop_config.json.
3. Add/modify the mcpServers block, adapting for your OS and configuration:

Claude Configuration (macOS / Windows with Docker Desktop)

{
  "mcpServers": {
    "jupyter": {
      "command": "docker",
      "args": [
        "run",
        "-i", 
        "--rm", 
        "-e", "SERVER_URL", 
        "-e", "TOKEN",
        "-e", "NOTEBOOK_PATH",
        "-e", "LOG_LEVEL=INFO", 
        "jupyter-mcp-server:latest" 
      ],
      "env": {
        "SERVER_URL": "http://host.docker.internal:8888", 
        "TOKEN": "YOUR_SECURE_TOKEN", 
        "NOTEBOOK_PATH": "notebook.ipynb" 
      }
    }
  }
}

Claude Configuration (Linux)

{
  "mcpServers": {
    "jupyter": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--network=host", 
        "-e", "SERVER_URL",
        "-e", "TOKEN",
        "-e", "NOTEBOOK_PATH",
        "-e", "LOG_LEVEL=INFO",
        "jupyter-mcp-server:latest"
      ],
      "env": {
        "SERVER_URL": "http://localhost:8888", 
        "TOKEN": "YOUR_SECURE_TOKEN", 
        "NOTEBOOK_PATH": "notebook.ipynb" 
      }
    }
  }
}

4. Save the config file and restart Claude Desktop.

Available Tools

This server provides the following tools for interacting with Jupyter:

• list_notebook_directory() → str
  • Lists files and directories in the same location as the current target notebook. Directories end with /.
• get_file_content(file_path: str, max_image_dim: int = 1024) → str
  • Retrieves file content. Text is returned directly. Images are resized if large (preserving aspect ratio, max dimension max_image_dim) and returned as a base64 Data URI string. Binary files described.
• set_target_notebook(new_notebook_path: str) → str
  • Changes the target notebook file path for subsequent tool calls (session only). Path must be relative.
• add_cell(content: str, cell_type: str, index: Optional[int] = None) → str
  • Adds a new cell ('code' or 'markdown') with specified content at index (appends if index is None or invalid). Uses robust Yjs type creation.
• add_code_cell_on_bottom(cell_content: str) → str
  • Adds a code cell at the end of the notebook.
• execute_cell(cell_index: int) → str
  • Sends execution request for a cell (fire-and-forget via asyncio.to_thread). Does not wait for completion. Returns confirmation message or error.
• execute_all_cells() → str
  • Sends execution requests for all code cells sequentially (fire-and-forget). Returns confirmation message or error.
• get_cell_output(cell_index: int, wait_seconds: float = OUTPUT_WAIT_DELAY) → str
  • Retrieves the combined text output(s) of a code cell, waiting briefly (wait_seconds). Returns output string or status message.
• delete_cell(cell_index: int) → str
  • Deletes a specific cell by its index.
• move_cell(from_index: int, to_index: int) → str
  • Moves a cell using a simple delete/re-insert approach for better live rendering stability.
• search_notebook_cells(search_string: str, case_sensitive: bool = False) → List[Dict[str, Any]]
  • Searches all cell sources for search_string. Returns list of matching cells [{'index', 'cell_type', 'source'}].
• split_cell(cell_index: int, line_number: int) → str
  • Splits a cell at a specific line_number (1-based). Uses robust Yjs type creation.
• get_all_cells() → list[dict[str, Any]]
  • Retrieves info for all cells [{'index', 'cell_type', 'source', 'execution_count'}]. Converts Yjs types to Python types.
• edit_cell_source(cell_index: int, new_content: str) → str
  • Replaces the source content of a specific cell. Uses correct Yjs Text API.
• get_kernel_variables(wait_seconds: int = 2) → str
  • Lists variables in the kernel namespace using %whos. Creates/executes/deletes a temporary cell.
• get_all_outputs() → dict[int, str]
  • Retrieves outputs for all code cells. Returns dict {index: output_string} or status like [No output], [Not executed].
• install_package(package_name: str, timeout_seconds: int = 60) → str
  • Installs a package into the kernel using !pip install. Creates/executes/deletes a temporary cell. Output includes pip logs.
• list_installed_packages(wait_seconds: int = 5) → str
  • Lists installed packages using !pip list. Creates/executes/deletes a temporary cell.

Troubleshooting

If you encounter issues during setup or usage, please consult the detailed troubleshooting guide which includes solutions found during debugging.

➡️ TROUBLESHOOTING.md

Building from Source

You can build the Docker image directly from the source code (which includes necessary patches):

# Make sure you are in the project's root directory (where Dockerfile is)
docker build -t jupyter-mcp-server:latest .

License and Copyright

This is an extended fork of the original jupyter-mcp-server by Datalayer, Inc. This version, significantly extended and debugged, expands upon the original functionality, fixing numerous issues and offering a much wider range of tools (15+ tools compared to the original 2-3) for manipulating notebooks, executing code, managing files, and interacting with the kernel.

This project is licensed under the BSD 3-Clause License. See the LICENSE file for the full text.

Copyright pertains to the respective contributors:

• Copyright (c) 2023-2024 Datalayer, Inc. (Original work)
• Copyright (c) 2025 Alexander Isaev (Modifications and additions)