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 endpointtype: The transport type, must be "streamable-http" for this serverheaders: HTTP headers to include in requests, typically including the Authorization header with the tokendisabled: Set totrueto disable this server configurationalwaysAllow: 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 notebooksget_notebook: Get notebook contentcreate_notebook_session: Create or retrieve a collaboration sessionupdate_notebook_cell: Update a notebook cellinsert_notebook_cell: Insert a new celldelete_notebook_cell: Delete a cellexecute_notebook_cell: Execute a cell
Document Operations
list_documents: List available documentsget_document: Get document contentcreate_document_session: Create or retrieve a collaboration sessionupdate_document: Update document contentinsert_text: Insert text at a positiondelete_text: Delete text from a positionget_document_history: Get document version historyrestore_document_version: Restore a document to a previous versionfork_document: Create a fork of a documentmerge_document_fork: Merge a fork back into the original
Awareness Operations
get_online_users: Get list of online usersget_user_presence: Get user presence informationset_user_presence: Set current user's presence statusget_user_cursors: Get cursor positions in a documentupdate_cursor_position: Update current user's cursor positionget_user_activity: Get recent user activitiesbroadcast_user_activity: Broadcast user activityget_active_sessions: Get active collaboration sessionsjoin_session: Join a collaboration sessionleave_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
- Authentication Errors: Make sure you're using the correct token in your Authorization header
- Connection Refused: Verify that your Jupyter server is running and the MCP extension is loaded
- 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