Jupyter MCP Server for Real-Time AI Notebooks

Overview

Jupyter MCP Server implements the Model Context Protocol (MCP) as a standalone service that integrates with any Jupyter deployment. It provides a real-time bridge between notebook frontends and model-driven tooling: allowing language models and other AI tools to edit cells, annotate code, generate documentation, and orchestrate executions in an interactive, streaming fashion.

By decoupling model interactions from a specific notebook server, the MCP server enables consistent AI behaviors across JupyterLab, classic notebooks, and hosted notebook platforms. Developers can deploy a single MCP endpoint that multiple notebook instances connect to, enabling collaboration, centralized logging, and easier management of model access and configuration.

Features

• Implements MCP endpoints for request/response and streaming (WebSocket) interactions.
• Pluggable model/back-end integration (connect models or proxies that implement the MCP operations).
• Context management: track notebook state, cell contents, execution results, and metadata.
• Real-time editing: apply suggested edits to cells and stream progressive outputs for long-running operations.
• Authentication and configuration via environment variables for easy deployment.
• Docker-friendly and runnable as a standalone Python service for local and cloud deployments.

Installation / Configuration

Install from GitHub (recommended for the latest source):

# Clone and install in editable mode
git clone https://github.com/datalayer/jupyter-mcp-server.git
cd jupyter-mcp-server
python -m venv .venv
source .venv/bin/activate
pip install -e .

Run the server locally (example using uvicorn for an ASGI app):

# Example: run on port 3000
uvicorn jupyter_mcp_server.app:app --host 0.0.0.0 --port 3000

Run with Docker (build from repository or pull an image if published):

# Build locally
docker build -t jupyter-mcp-server .
docker run -p 3000:3000 \
  -e MCP_SERVER_PORT=3000 \
  -e MCP_AUTH_TOKEN="your-token" \
  jupyter-mcp-server

Configuration is primarily through environment variables. Create a .env file or set variables in your container/orchestration system:

MCP_SERVER_PORT=3000
MCP_AUTH_TOKEN=replace-with-secure-token
JUPYTER_BASE_URL=http://localhost:8888
LOG_LEVEL=info

After starting the server, configure your Jupyter environment or extensions to point at the MCP server base URL (for example: http://your-mcp-host:3000).

Available Resources

Common endpoints and resources provided by the server (paths may vary depending on configuration):

• HTTP status and metadata: GET /status
• REST MCP API: POST /mcp (synchronous requests)
• WebSocket streaming: ws://host:PORT/mcp/ws (for interactive sessions and streaming edits)
• OpenAPI or docs (if enabled in deployment): GET /docs

Table: Typical environment variables

Refer to the repository README and source for exact paths and additional configuration options.

Use Cases

• Real-time code assistance: A model can propose edits to a notebook cell and stream those edits over the WebSocket connection. The notebook frontend applies changes as they arrive, enabling an interactive authoring experience.

  • Example: a user requests a refactor; the model streams a sequence of patch operations that update multiple cells without blocking the UI.

• Automated documentation: The MCP server can generate documentation cells based on surrounding code and previous outputs. Developers can trigger scripted documentation runs that append or update Markdown cells describing functions, parameters, or visualization choices.

• Model-driven execution orchestration: Use the MCP server to coordinate multi-step analysis where an assistant suggests a sequence of notebook executions, captures results, and updates context. This is helpful for iterative experiments or reproducible analysis.

• Collaborative workflows: Deploy a centralized MCP server that multiple users or notebook instances connect to. This supports shared model state, audit logs of suggested edits, and consistent tooling across teams.

Example: simple WebSocket client (JavaScript)

const ws = new WebSocket("ws://localhost:3000/mcp/ws", ["mcp-protocol"]);
ws.onopen = () => {
  ws.send(JSON.stringify({ type: "identify", token: "your-token", notebook_id: "nb-123" }));
  ws.send(JSON.stringify({ type: "request", action: "explain_cell", cell_id: "cell-5" }));
};
ws.onmessage = (evt) => {
  const msg = JSON.parse(evt.data);
  console.log("MCP message:", msg);
};

Example: triggering a synchronous MCP request (Python)

import requests
resp = requests.post(
    "http://localhost:3000/mcp",
    headers={"Authorization": "Bearer your-token"},
    json={"action": "generate_doc", "notebook_id": "nb-123", "cell_id": "cell-5"}
)
print(resp.json())

Getting Help and Contributing

For code-level details, configuration options, and contribution guidelines, see the project repository: https://github.com/datalayer/jupyter-mcp-server. Issues and pull requests on GitHub are the primary channels for support and feature requests.