jupyter-mcp-server is a specialized MCP Server designed to bridge AI models with Jupyter notebooks running in any JupyterLab environment, enabling real-time interaction. It acts as a crucial link, allowing AI clients, such as Claude Desktop, to directly engage with your interactive coding sessions. Key features include tools to programmatically add and execute code cells (add_execute_code_cell) or insert markdown content (add_markdown_cell) into a target notebook. This seamless integration empowers developers by enabling AI assistants to directly manipulate notebook content based on conversational prompts, streamlining data science and development workflows. Typically deployed via Docker, it connects securely to your specified JupyterLab instance, requiring simple configuration within the AI client. jupyter-mcp-server transforms how developers leverage AI within their familiar, powerful Jupyter environment, making notebook interaction more dynamic and AI-driven.

Remote Notebook Execution

This core feature enables AI models, through an MCP client, to execute code directly within a user's active Jupyter notebook session. The jupyter-mcp-server acts as a bridge, receiving instructions from the AI client via the Model Context Protocol. Specifically, it utilizes the add_execute_code_cell tool. When invoked, the server connects to the specified JupyterLab instance (using the provided SERVER_URL and TOKEN) and injects a new code cell containing the cell_content provided by the AI. It then triggers the execution of this cell within the Jupyter kernel associated with the target notebook (NOTEBOOK_PATH). The server captures the output generated by the executed code (e.g., text results, variable values, error messages) and sends it back to the AI model via the MCP client. This allows the AI to perform complex computations, data manipulations, or visualizations within the user's environment, leveraging their existing libraries and data context. For example, an AI could be asked to "Plot the distribution of column 'X' in the current DataFrame," and it would use this tool to generate and execute the necessary Python plotting code.

Dynamic Notebook Content Generation

The jupyter-mcp-server empowers AI models to add descriptive or structural content to a Jupyter notebook using the add_markdown_cell tool. Similar to code execution, the AI client sends a request containing the desired Markdown content (cell_content) to the MCP server. The server then interacts with the target JupyterLab session, authenticating using the configured token, and inserts a new Markdown cell into the specified notebook (NOTEBOOK_PATH). This cell contains the text formatted according to Markdown syntax provided by the AI. Unlike code execution, this tool typically just returns a success confirmation. This functionality is crucial for enabling AI to document code it generates, explain analysis steps, summarize findings, or structure the notebook with headings and explanatory text. For instance, after generating a complex plot, the AI could use add_markdown_cell to insert a textual explanation of the visualization directly below it in the notebook, creating a more comprehensive and understandable record of the analysis. This enhances the notebook as a narrative document, combining code, results, and AI-driven explanations seamlessly.

Seamless JupyterLab Integration

This feature represents the fundamental capability of jupyter-mcp-server to connect and interact securely with a running JupyterLab instance, regardless of whether it's local or remote. The integration relies on standard web protocols and Jupyter's own APIs. Configuration requires specifying the JupyterLab server's URL (SERVER_URL, often using host.docker.internal or localhost depending on the Docker network setup) and the authentication token (TOKEN) set when launching JupyterLab. The server uses these details to establish a connection. The requirement to launch JupyterLab with --ip 0.0.0.0 makes it accessible from outside its local machine, specifically enabling the MCP server (often running in a Docker container) to reach it. The NOTEBOOK_PATH parameter directs the server's actions to the correct file within the Jupyter environment. This setup effectively turns a standard JupyterLab session into an MCP-compatible resource, allowing any MCP client configured with this server to interact with the specified notebook. This solves the critical problem of bridging the gap between conversational AI interfaces and the powerful, stateful execution environment of Jupyter notebooks in a standardized and secure manner.