@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.
• Auto Start: In non-mock mode, the Jupyter server starts during MCP server startup.

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 notebook fallbacks) with --no-browser.
• The Jupyter runtime is initialized before the MCP server finishes startup, so list_tools and later tool calls share the same ready runtime.
• After the server is ready, it opens the Jupyter UI in your default browser (if JUPYTER_AUTO_OPEN is not false).
• If JUPYTER_START_NOTEBOOK_PATH is set, that notebook is opened directly; otherwise the root Jupyter UI is opened.

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 server starts.
• JUPYTER_START_NOTEBOOK_PATH: Notebook to open automatically on startup.
• JUPYTER_KERNEL_NAME: Kernel name used when code execution needs to create a kernel. Defaults to python3.