jupyter-mcp-server

Implements a FastMCP-based server that translates Model Context Protocol messages from AI clients (Claude Desktop, VS Code, Cursor) into Jupyter API calls, using STDIO and HTTP transports with CORS middleware. The server maintains a singleton ServerContext for configuration and routes requests through a tool registry to 15+ specialized notebook operation tools, enabling stateful interaction with Jupyter kernels and notebook documents.

The NotebookManager component maintains isolated session state for multiple notebooks, tracking kernel connections, cell execution order, and output buffers per notebook. It implements session lifecycle management (open, close, switch) and routes execution requests to the correct kernel instance, enabling AI clients to work with multiple notebooks in parallel without cross-contamination of kernel state or variable scope.

Distributes the MCP server as a multi-architecture Docker image (datalayer/jupyter-mcp-server) supporting amd64 and arm64 platforms. The Dockerfile installs the jupyter-mcp-server package and Jupyter dependencies, enabling one-command deployment in containerized environments. The image includes both standalone server and extension modes, selectable via environment variables or command-line arguments.

Captures and processes cell execution outputs in multiple MIME types (text/plain, text/html, image/png, image/svg+xml, application/json), converting matplotlib figures and pandas DataFrames into base64-encoded images or HTML. The output processor preserves the original MIME type metadata, allowing clients to render outputs appropriately (display images, render tables, parse JSON).

Implements ServerContext singleton that loads configuration from environment variables and optional config files, managing settings like Jupyter Server URL, authentication tokens, notebook paths, and deployment mode (standalone vs. extension). Configuration is loaded at server startup and cached in memory, allowing clients to query current settings via tools.

Implements comprehensive error handling that captures kernel errors (syntax errors, runtime exceptions, timeouts), network errors (connection failures, timeouts), and MCP protocol errors (invalid requests, schema violations). Errors are returned to clients with detailed diagnostic information (error type, traceback, execution context) enabling AI clients to understand failures and retry intelligently.

Provides pre-built prompt templates (via MCP's prompts/list and prompts/get endpoints) that guide AI clients in common notebook tasks like code review, debugging, data exploration, and documentation generation. Templates include context about notebook structure and execution state, reducing the need for clients to construct prompts from scratch.

Exposes tools for reading notebook cell contents (code, markdown, raw) and writing new cells with position control (before, after, replace). The implementation preserves notebook structure by respecting cell boundaries and execution order, allowing AI clients to inspect code context before modification and insert cells at semantically meaningful positions without corrupting the notebook document structure.

Executes notebook cells against a live kernel using Jupyter's execute_request message protocol, capturing stdout, stderr, and structured outputs (plots, dataframes, images) in real-time. Supports both blocking execution (wait for completion) and non-blocking execution (poll for results), with output buffering that preserves multimodal content including matplotlib figures and pandas DataFrames rendered as HTML.

Provides tools to inspect notebook metadata (kernel name, language, nbformat version), query kernel status (idle, busy, dead), and retrieve execution history (cell execution counts, timestamps). Implements polling-based kernel health monitoring that allows AI clients to determine if a kernel is ready for execution or if previous operations are still in flight.

Implements tools that interact with JupyterLab's frontend state, including setting the active cell, scrolling to a cell, and triggering UI actions (save, run). Uses JupyterLab's message protocol to communicate with the frontend, allowing AI clients to control the notebook view and focus without requiring direct browser automation or UI scripting.

Implements tools to read and write notebook files (.ipynb) from the filesystem, preserving the Jupyter notebook JSON structure, cell metadata, and output artifacts. Uses Jupyter's nbformat library to parse and serialize notebooks, ensuring compatibility with Jupyter's format versioning and preventing corruption of notebook files during read-write cycles.

Implements MCP's tools/list and tools/describe endpoints to dynamically advertise the 15+ available tools with their schemas, parameters, and descriptions. The tool registry is populated at server startup from the tools/ directory, allowing clients to discover capabilities without hardcoding tool names. Each tool includes JSON Schema definitions for input validation and output typing.

Deploys the MCP server as a standalone process (default port 4040) using FastAPI with CORS middleware, enabling HTTP-based MCP clients to connect without STDIO pipes. The server implements FastMCPWithCORS, a custom FastMCP subclass that adds CORS headers for cross-origin requests, allowing web-based MCP clients and browser extensions to communicate with the server.

Deploys the MCP server as a Jupyter Server extension (handlers.py), embedding it directly into the Jupyter Server process without requiring a separate service. The extension registers MCP endpoints alongside Jupyter's native API, allowing clients to connect via the same WebSocket or HTTP connection as the notebook frontend, with automatic authentication inheritance from Jupyter's session management.