ipynb-mcp

An agent-agnostic MCP server that lets any AI agent (Claude Code, OpenAI Codex, etc.) drive a local JupyterLab session via the Model Context Protocol.

Getting started with an AI agent

After installation, use one of the following prompts to kick off a session.

Fresh start (no server running):

Start a new notebook project using ipynb-mcp. Venv is at ~/lib/python/uv-osm, notebook dir is /path/to/notebooks. Project goal: [one sentence description].

Reconnect to an already-running JupyterLab:

Continue a notebook project using ipynb-mcp. JupyterLab is already running on port 8888 with token [token]. Notebook dir is /path/to/notebooks. Continue working on [notebook.ipynb].

The token is printed to the terminal when JupyterLab starts — look for a line like:

http://localhost:8888/lab?token=abc123...

Known limitation: browser reload required

When the agent writes or updates cells via the REST API, JupyterLab's browser tab does not auto-refresh. After the agent makes changes, reload the notebook manually with File → Reload Notebook from Disk to see the latest cells and outputs.

Related MCP server: mcp-devtools

How it works

┌─────────────────────┐  stdio (MCP)  ┌───────────────────┐
│   AI agent          │◄─────────────►│   ipynb-mcp       │
│  (Claude Code /     │               │   (this server)   │
│   OpenAI Codex /    │               │         │         │
│   any MCP client)   │               │  Jupyter REST API │
└─────────────────────┘               │  + kernel WS      │
                                      │         │         │
                                      │  JupyterLab       │
                                      │  (subprocess)     │
                                      └───────────────────┘

Unlike colab-mcp (which proxies tools from a remote browser extension), ipynb-mcp talks directly to the Jupyter REST API and kernel WebSocket — no browser extension required.

Installation

This project uses the shared uv-osm virtual environment. Always activate it before running any commands.

Prerequisites

source ~/lib/python/uv-osm/bin/activate && uv pip install jupyterlab

Install ipynb-mcp

source ~/lib/python/uv-osm/bin/activate && cd ipynb-mcp && uv pip install -e .

Note: Use uv pip install (not plain pip install). Never install packages globally.

Configuring your agent

Use the full venv binary path in all agent configs so the server always runs inside the correct environment regardless of the shell's active venv.

Claude Code

Register the server once, from your project root directory (not from inside the ipynb-mcp source folder — Claude Code scopes MCP servers to the directory where the command is run):

cd /path/to/your/project
claude mcp add ipynb-mcp -- /home/<user>/lib/python/uv-osm/bin/ipynb-mcp

Verify it registered correctly by running /mcp in the Claude Code prompt — you should see ipynb-mcp · ✔ connected in the server list. If the server doesn't appear, check that you ran claude mcp add from the right directory. The server starts on demand when a tool is called; no manual pre-launch needed.

Or add to .claude/mcp.json in your project:

{
  "mcpServers": {
    "ipynb-mcp": {
      "command": "/home/<user>/lib/python/uv-osm/bin/ipynb-mcp",
      "args": []
    }
  }
}

Replace /home/<user> with your actual home directory (or use the ~ expansion if your client supports it).

Generic mcp.json (OpenAI Codex, Cursor, Zed, etc.)

Most MCP-compatible clients read a configuration file. Create or extend mcp.json:

{
  "mcpServers": {
    "ipynb-mcp": {
      "command": "/home/<user>/lib/python/uv-osm/bin/ipynb-mcp",
      "args": [],
      "env": {
        "IPYNB_MCP_NOTEBOOK_DIR": "/path/to/your/notebooks",
        "IPYNB_MCP_PORT": "8888"
      }
    }
  }
}

Using the full venv path ensures the server finds all its dependencies without needing the shell to be activated first.

Environment variables

Available tools

Typical agent workflow

agent → start_jupyter()           # launches JupyterLab, opens browser
agent → open_notebook("work.ipynb")
agent → add_text_cell(path, "# My analysis")
agent → add_code_cell(path, "import pandas as pd\ndf = pd.read_csv('data.csv')")
agent → run_code_cell(path, cell_id)   # executes, returns outputs
agent → get_cells(path)                # inspect outputs
agent → update_cell(path, cell_id, "...fixed code...")
agent → run_code_cell(path, cell_id)

Differences from colab-mcp