Jupyter MCP Server

Jupyter MCP Server is a Model Context Protocol (MCP) server implementation that provides AI models with real-time interaction capabilities for Jupyter Notebooks. It allows an AI to edit, document, and execute code for tasks such as data analysis and visualization.

Key capabilities include:

• Real-time control: Instant visibility of notebook changes.
• Smart execution: Automatic adjustments based on cell output feedback when runs fail.
• Context-awareness: Full understanding of the notebook context.
• Multimodal support: Handles various output types including images, plots, and text.
• Multi-notebook support: Ability to switch between different notebooks.
• JupyterLab integration: Features like automatic notebook opening.
• MCP Compatibility: Works with clients like Claude Desktop, Cursor, Cline, and Windsurf.

The project is organized into several layers that separate the CLI, the MCP protocol, and the Jupyter integration:

• cli/: The Typer-based command-line interface for starting/stopping the server.
• server.py: The FastMCP server layer handling the MCP protocol, tool registration, and transport (stdio/HTTP).
• tools/: The implementation of the 14 built-in tools.
• notebook_manager.py: Manages notebook lifecycles, kernel connections, and dual-mode operations.
• jupyter_extension/: The actual Jupyter Server extension code, including backends/ for local/remote API abstraction.
• config.py: Manages singleton configuration and environment variables.
• models.py: Pydantic models for API data structures (Cells, Notebooks, etc.).
• hooks.py: A hook system for event-driven extensions (e.g., OpenTelemetry).

The Jupyter MCP Server is compatible with any client that implements the Model Context Protocol (MCP). It supports both STDIO and streamable HTTP transports.

Validated clients include:

• Claude Desktop
• VS Code
• Cursor
• Cline
• Windsurf

You can find a broader list of compatible clients in the official MCP clients documentation. For a CLI-based client approach, you can use the mcp-client-cli Python package.

By default, the server uses the jupyter engine. You can route execution through other backends by setting SANDBOX_VARIANT. To use non-jupyter variants, you must install the jupyter_mcp_sandboxes extension (pip install jupyter_mcp_sandboxes).

The Jupyter MCP Server bundle is built using the UV code sandbox type. This architecture provides several benefits:

• Environment Management: Claude Desktop automatically manages the Python environment.
• Dependency Isolation: All dependencies (including jupyter-mcp-server) are installed via uv into an isolated virtual environment, ensuring no changes are made to your system-wide Python installation.
• Communication: The server operates in stdio transport mode for direct communication with Claude Desktop.

Bundle File Structure:

• manifest.json: Contains extension metadata, tool definitions, and user configuration requirements.
• pyproject.toml: Defines the Python dependencies used by the UV code sandbox.
• .mcpbignore: Specifies files to be excluded from the bundle.
• src/server.py: The entry point that launches the MCP server.

While Monty is extremely fast and secure, it has specific constraints compared to full Jupyter kernels:

• Python Subset: Monty only supports a restricted subset of Python.
• No Third-Party Libraries: Libraries like numpy or pandas are not available.
• No Rich Outputs: Images, plots, and other rich display outputs are not supported.
• Persistence: Session state (variables, imports, and definitions) does persist across cell executions, behaving like a regular kernel.

If you require third-party libraries or rich outputs, use the jupyter, datalayer, kaggle, colab, or modal engines instead.

When using the Modal provider, each code execution runs in a fresh python -c process.

Important: Kernel state does not persist across separate tool calls. If you need to maintain state (e.g., defining a variable in one step and using it in another), you must combine those statements into a single cell/tool call.

The Jupyter MCP Server operates in two distinct modes depending on how you want to connect to your Jupyter environment. Both modes use the same underlying tool implementations, but they differ in how they communicate with the Jupyter backend:

1. MCP_SERVER Mode (Standalone): This mode runs as a separate process. It connects to remote Jupyter servers using standard web protocols like HTTP or WebSockets. This is ideal if your Jupyter server is running on a different machine or in a container.

2. JUPYTER_SERVER Mode (Extension): This mode runs as an embedded extension directly inside a Jupyter Server. It has direct access to the Jupyter API, providing zero-overhead communication and support for features like YDoc. This is ideal for local development or when you want the MCP capabilities integrated into your existing Jupyter session.

When deploying for multiple users, avoid sharing a single MCP server instance with a shared JupyterLab, as this causes a 'Concurrency Problem' where agents interfere with each other's active notebooks.

There are three primary architecture patterns:

1. One MCP Server Per User (Recommended): Each user gets an isolated MCP server instance via JupyterHub. This provides complete isolation and scales naturally.
2. Stateless Tool Operations (Under Development): Tools will eventually require explicit notebook paths (e.g., notebook: "user1/analysis.ipynb") to avoid relying on 'active notebook' state.
3. Session-Based Isolation (Experimental): Using unique session identifiers to isolate contexts within a shared server.

Decide which transport method to use based on your deployment requirements:

STDIO Transport

• Best for: Desktop applications (e.g., Claude Desktop, Cursor, Windsurf, VS Code), Docker deployments, and single-user setups.
• Pros: Simple configuration; works with most MCP clients; no additional server ports needed.
• Cons: Supports only one client connection at a time.

Streamable HTTP Transport

• Best for: Web applications, multiple concurrent clients, and production deployments.
• Pros: Multiple clients can connect simultaneously; web-based access; can run as a Jupyter Server Extension (no separate process required).
• Cons: Requires opening network ports.