open-index/open-npm huggingface dataset:
npm package: @fre4x/jupyter
Description: Jupyter Notebook MCP server
Latest version: 1.0.54

# @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
```bash
MOCK=true npx @fre4x/jupyter
```

### Claude Desktop Configuration
```json
{
  "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`.