jupyter

Jupyter MCP Server provides a bridge between AI systems and Jupyter Notebook workspaces using the Model Context Protocol (MCP). It enables an AI assistant to manage and orchestrate operations across multiple notebooks, including connecting to or creating notebooks, inspecting and editing cells, executing code, and receiving multimodal outputs such as text, images, and tables. Core tooling exposed by the server includes: connect_notebook to open or create a notebook, list_notebook to enumerate active notebooks, restart_notebook to reset a notebook’s environment, and read_notebook to fetch the source of a notebook without outputs. For cell-level workflows, you can list_cell, read_cell, delete_cell, insert_cell, and execute_cell to run cells and retrieve their outputs. Higher-level capabilities like append_execute_code_cell and execute_temporary_code let you append code to the end of a notebook and execute it, or run ad-hoc code blocks without persisting changes. This setup is designed for multi-notebook scenarios and multimodal feedback, making it suitable for AI IDEs or CLI tools that require structured, interactive notebook management.

Prerequisites:

• Python 3.12+ (recommended) and a Python environment you can activate.
• uvx (via the uv package) for executing MCP servers, or use your preferred MCP runtime that supports the MCP spec.
• Access to the project repository (clone from GitHub).

1. Install uvx (Python MCP runtime) and dependencies:

# Install uvx if you haven't already (example using pipx or pip depending on your setup)
pipx install uvx
# or
pip install uvx

2. Clone the MCP server repository and install Python dependencies:

git clone https://github.com/ChengJiale150/jupyter-mcp-server
cd jupyter-mcp-server
pip install -r requirements.txt  # if a requirements file exists

3. Configure the MCP JSON (example) and run via uvx:

# Example config (save as mcp_config.json or embed in your MCP runtime config)

4. Start the MCP server using uvx with the provided config:

uvx run --directory /path/to/jupyter-mcp-server src/main.py

5. Verify startup output indicates the MCP server is listening on stdio transport (e.g., starting messages).

Note: If you prefer running the server directly with Python, you can adapt the command to your runtime by pointing to the main entry of the project (for example, python -m better_jupyter_mcp_server or python src/main.py, depending on the package structure). The README example uses uvx with a standard stdio transport for MCP clients.

Tips and caveats:

• The recommended runtime is uvx with stdio transport, as shown in the example configuration. Ensure ALLOW_IMG is set when you expect image outputs from notebook operations.
• The tooling supports multiple notebooks, and some operations may take longer (e.g., connecting/creating a notebook or executing a cell). Plan tasks accordingly.
• When integrating with clients, provide multimodal-capable clients (e.g., Cursor or Gemini CLI) to fully leverage image and table outputs.
• If you encounter issues starting the server, verify Python version, ensure required dependencies are installed, and check that the transport (stdio) is properly configured in your MCP client.
• The configuration can be extended with additional environment variables or transport options depending on your deployment and security needs.
• For local testing, you can follow the README’s examples to manually start a Jupyter server and then connect it through MCP rules and prompts.