Jupyter Collaboration MCP Server

A JupyterLab extension that provides MCP (Model Context Protocol) server endpoints to expose Jupyter Collaboration's real-time collaboration (RTC) functionalities to AI agents.

Overview

This project enables AI agents to interact with collaborative Jupyter notebooks and documents in real-time. It leverages the existing Jupyter Collaboration system's robust RTC capabilities using YDoc (CRDT) technology and exposes them through MCP endpoints.

Features

• Notebook Collaboration: Real-time collaboration on Jupyter notebooks with AI agents
• Document Collaboration: Shared document editing with version control and forking
• User Awareness: Track user presence, cursor positions, and activity
• Real-time Communication: Streamable HTTP for bidirectional communication
• Authentication & Authorization: Integrated with Jupyter's security infrastructure
• Resumable Streams: Clients can reconnect and resume from where they left off

Installation

Prerequisites

• Python 3.10 or higher
• Jupyter Server 2.0.0 or higher
• Jupyter Collaboration 2.0.0 or higher

From Conda (when published)

conda install -c conda-forge jupyter-collaboration-mcp

From PyPI (when published)

pip install jupyter-collaboration-mcp

From Source

git clone https://github.com/jupyter/jupyter-collaboration-mcp.git
cd jupyter-collaboration-mcp
pip install -e .

Configuration

The MCP server is automatically loaded as a Jupyter server extension when installed. No manual configuration is required.

Authentication

The MCP server uses simple token-based authentication. When running as a Jupyter server extension, it automatically uses the token provided via the --IdentityProvider.token command line option.

Using Jupyter Lab Tokens

When starting Jupyter Lab, you can provide a token for authentication:

jupyter lab --IdentityProvider.token=your-secret-token

This token can then be used to authenticate with the MCP server.

MCP Client Configuration

For MCP clients, you'll need to configure the server URL and authentication token. The exact configuration depends on your MCP client, but it typically looks like this:

Example MCP Client Configuration

{
  "mcpServers": {
    "jupyter-collaboration": {
      "url": "http://localhost:8888/mcp",
      "type": "streamable-http",
      "headers": {
        "Authorization": "Identity.token your-secret-token"
      },
      "disabled": false
    }
  }
}

Configuration Parameters

• url: The URL of the MCP server endpoint
• type: The transport type, must be "streamable-http" for this server
• headers: HTTP headers to include in requests, typically including the Authorization header with the token
• disabled: Set to true to disable this server configuration
• alwaysAllow: Optional list of tools that should always be allowed (if supported by your client)

Finding Your Server URL

• When running as a Jupyter server extension, the MCP endpoint is typically at http://localhost:8888/mcp (or whatever port your Jupyter server is running on)

Provided MCP Tools

The server exposes the following MCP tools:

Notebook Operations

• list_notebooks: List available notebooks
• get_notebook: Get notebook content
• create_notebook_session: Create or retrieve a collaboration session
• update_notebook_cell: Update a notebook cell
• insert_notebook_cell: Insert a new cell
• delete_notebook_cell: Delete a cell
• execute_notebook_cell: Execute a cell

Document Operations

• list_documents: List available documents
• get_document: Get document content
• create_document_session: Create or retrieve a collaboration session
• update_document: Update document content
• insert_text: Insert text at a position
• delete_text: Delete text from a position
• get_document_history: Get document version history
• restore_document_version: Restore a document to a previous version
• fork_document: Create a fork of a document
• merge_document_fork: Merge a fork back into the original

Awareness Operations

• get_online_users: Get list of online users
• get_user_presence: Get user presence information
• set_user_presence: Set current user's presence status
• get_user_cursors: Get cursor positions in a document
• update_cursor_position: Update current user's cursor position
• get_user_activity: Get recent user activities
• broadcast_user_activity: Broadcast user activity
• get_active_sessions: Get active collaboration sessions
• join_session: Join a collaboration session
• leave_session: Leave a collaboration session

Development Setup

Prerequisites

• Python 3.10 or higher
• Git
• Node.js (for JupyterLab extension development, if needed)

Clone the Repository

git clone https://github.com/jupyter/jupyter-collaboration-mcp.git
cd jupyter-collaboration-mcp

Create a Virtual Environment

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install Dependencies

pip install -e ".[dev]"

This will install the package in development mode along with all development dependencies.

Code Formatting

The project uses Black for code formatting and isort for import sorting. You can format code manually:

black jupyter_collaboration_mcp tests
isort jupyter_collaboration_mcp tests

Auto-formatting on Commit

To set up automatic code formatting on each commit, run the setup script:

./scripts/setup-git-hooks.sh

This will set up a Git hook that automatically formats your Python files with black and isort before each commit.

Type Checking

The project uses mypy for type checking:

mypy jupyter_collaboration_mcp

Troubleshooting

Common Issues

1. Authentication Errors: Make sure you're using the correct token in your Authorization header
2. Connection Refused: Verify that your Jupyter server is running and the MCP extension is loaded
3. CORS Errors: If running in a browser environment, make sure the server's CORS configuration allows your client's origin

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Jupyter Collaboration for the underlying RTC functionality
• Model Context Protocol (MCP) for the AI agent communication standard
• Jupyter Server for the server infrastructure