@fre4x/jupyter

@fre4x/jupyter

Jupyter Notebook MCP server for reading, writing, executing code in .ipynb files, and launching a local Jupyter UI.

Features

• Read/Write: Full support for .ipynb (JSON) manipulation.
• Execute: Run code cells in a real Jupyter kernel over the Jupyter WebSocket protocol.
• Control: Launch or connect to a local Jupyter server, list kernels, and open notebooks in the browser.
• Mock Mode: Development without a real Jupyter server using MOCK=true.
• Lazy Runtime: In non-mock mode, the Jupyter runtime starts only when a tool needs it.

Tools

• jupyter_get_notebook: Read a Jupyter notebook (.ipynb) file.
• jupyter_create_notebook: Create a new empty Jupyter notebook.
• jupyter_add_cell: Add a new cell (code/markdown) to a notebook.
• jupyter_update_cell: Update the content of an existing cell.
• jupyter_execute_code: Execute code in a real Jupyter kernel.
• jupyter_list_kernels: List all active Jupyter kernels.
• jupyter_open_notebook: Open a notebook in the default browser or viewer.

Usage

Mock Mode

MOCK=true npx @fre4x/jupyter

Claude Desktop Configuration

{
  "mcpServers": {
    "jupyter": {
      "command": "npx",
      "args": ["-y", "@fre4x/jupyter"],
      "env": {
        "JUPYTER_ROOT_DIR": "/absolute/path/to/notebooks",
        "JUPYTER_AUTO_OPEN": "true",
        "JUPYTER_START_NOTEBOOK_PATH": "/absolute/path/to/notebooks/demo.ipynb"
      }
    }
  }
}

Requirements

• Node.js 18+
• JupyterLab or Jupyter Notebook installed locally for managed startup, or JUPYTER_SERVER_URL pointing at an existing server.
• xdg-open / open / Windows shell integration for browser launch.

Runtime Behavior

• MOCK=true keeps the old fixture-only behavior.
• Without MOCK=true, the server first tries JUPYTER_SERVER_URL if provided.
• Otherwise it launches a local Jupyter process (jupyter lab, then multiple jupyter notebook / jupyter-notebook compatibility fallbacks for Notebook 7 and Notebook 6) with --no-browser when a runtime-backed tool is called.
• MCP startup no longer depends on Jupyter being installed locally; missing Jupyter is reported when a runtime-backed tool is called.
• When external launchers such as jupyter, jupyter-lab, jupyter-notebook, or desktop openers are missing, the tool response explains what is missing and tells the caller to install it directly or ask the user to install/configure it.
• JUPYTER_AUTO_OPEN and JUPYTER_START_NOTEBOOK_PATH are still honored, but only when the first runtime-backed tool initializes Jupyter.
• jupyter_open_notebook opens the Jupyter UI in your default browser and starts the runtime on demand if needed.

Environment Variables

• JUPYTER_SERVER_URL: Use an already-running Jupyter server instead of launching one.
• JUPYTER_TOKEN: Optional token for an external Jupyter server.
• JUPYTER_ROOT_DIR: Root directory for managed Jupyter startup. Defaults to the current working directory.
• JUPYTER_AUTO_OPEN: Set to false to skip browser launch when the first runtime-backed tool initializes Jupyter.
• JUPYTER_START_NOTEBOOK_PATH: Notebook to open automatically when the first runtime-backed tool initializes Jupyter.
• JUPYTER_KERNEL_NAME: Kernel name used when code execution needs to create a kernel. Defaults to python3.