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)

From PyPI (when published)

From Source

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:

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

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

Create a Virtual Environment

Install Dependencies

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:

Auto-formatting on Commit

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

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:

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