mcp -jupyter

This MCP server provides programmatic control over Jupyter notebooks. It exposes six tools for notebook manipulation: read_notebook_with_outputs reads a notebook including cell outputs, read_notebook_source_only reads content without outputs, read_output_of_cell fetches the output of a specific cell, add_cell inserts a new cell with optional type and position, edit_cell updates an existing cell by its ID, and execute_cell runs a single cell and returns its output. These tools enable remote automation of notebook workflows, such as extracting results, modifying notebooks, and validating cell execution, all via the MCP interface.

To use the server, configure the MCP client (e.g., Claude Desktop) to connect to the UV-based MCP server as shown in the README example. Ensure your Claude environment uses a dedicated Python virtual environment where Jupyter is installed. When invoking tools, pass full paths to notebooks and the appropriate identifiers (notebook_path, cell_id, etc.). Remember to reload the notebook page after add_cell or edit_cell operations to reflect changes in the Jupyter UI.

Prerequisites:

• Python 3.8+ installed on your system
• Access to install and run Python packages (pip or pipx)
• JupyterLab (or Jupyter Notebook) installed in the virtual environment you plan to use

Install and run the MCP server locally:

1. Create and activate a Python virtual environment (recommended):
   • uv venv --seed
   • source .venv/bin/activate
2. Install JupyterLab inside the virtual environment:
   • uv pip install jupyterlab
3. Install the MCP server package (the mcp-server-jupyter component) within the same environment. If this is a local repo, ensure your environment can import it as a package (e.g., via editable install or proper path mapping in the uv command).
4. Launch the MCP server via UV using the configuration described in mcp_config:
   • uv run --with mcp-server-jupyter mcp-server-jupyter
5. Ensure the UV_PROJECT_ENVIRONMENT is set to the path of your virtual environment in the environment running the MCP server:
   • UV_PROJECT_ENVIRONMENT=/path/to/venv_for_jupyter/.venv

Notes:

• The README example shows starting JupyterLab within the venv and using Claude Desktop to connect to the MCP server. Keep the JupyterLab instance running while interacting with Claude.
• If you modify notebook content via the MCP tools, manually reload the notebook in JupyterLab/Jupyter Notebook to see updates.

Environment variables and paths are critical. Set UV_PROJECT_ENVIRONMENT to the full path of your venv. When using Claude Desktop, provide full notebook paths to tools. If you encounter issues with cell IDs, ensure the notebook is opened and the IDs correspond to the actual cells in the current notebook. For large notebooks, prefer read_notebook_source_only to avoid transferring extensive outputs. Ensure JupyterLab is running in the same environment as the MCP server to avoid path or package resolution issues.