MCP Jupyter Notebook Server

A Model Context Protocol (MCP) server that gives AI agents full control over a live Jupyter notebook session — run code, add markdown, manage packages, inspect variables, and more. Built on agent-jupyter-toolkit and the MCP Python SDK.

Features

• Rich MCP tool surface — notebook lifecycle, code execution, markdown, stable cell-ID operations, packages, kernel control, introspection, variables
• Optional PostgreSQL tools — enable on demand to create a DB client/connection in the kernel
• Real-time sync — Yjs collaboration transport shows cell edits instantly in JupyterLab
• Two session modes — connect to a remote Jupyter server or run a local kernel
• Three transports — stdio (for editors), SSE, or streamable HTTP
• MCP SDK compatibility — supports the 1.26 API and the 2.x MCPServer API
• Observable collaboration policy — required, preferred with classified fallback, or disabled
• Zero config defaults — sensible defaults with full override via CLI args or env vars

Quick Start

1. Start a Jupyter server

# With Docker (recommended — includes jupyter-collaboration)
cd quickstarts && docker compose up -d --build

# Or locally
pip install jupyterlab ipykernel jupyter-collaboration
jupyter lab --port 8888 --IdentityProvider.token=mcp-dev-token

2. Configure your editor

VS Code — create .vscode/mcp.json:

{
  "servers": {
    "jupyter": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "${workspaceFolder}", "mcp-jupyter-notebook"],
      "env": {
        "MCP_JUPYTER_SESSION_MODE": "server",
        "MCP_JUPYTER_BASE_URL": "http://localhost:8888",
        "MCP_JUPYTER_TOKEN": "mcp-dev-token",
        "MCP_JUPYTER_NOTEBOOK_PATH": "agent_demo.ipynb"
      }
    }
  }
}

See the quickstart guide for Cursor, Claude Desktop, and published (uvx) vs local dev configs.

Optional: enable PostgreSQL tools

To add database helper tools, set either:

• MCP_JUPYTER_ENABLE_TOOLS=postgresql (env var), or
• --enable-tools postgresql (CLI flag)

In server mode, the kernel runs on the Jupyter server, so database env vars (like PG_DSN) must be set in the Jupyter server environment (see quickstarts/docker-compose.yml with docker compose --profile postgres).

Note: enabling tools only controls tool registration. Your PostgreSQL service must still be running and ready to accept connections (the quickstart Compose profile includes a healthcheck).

The PostgreSQL tools will use PG_DSN / POSTGRES_DSN / DATABASE_URL (in that order), or fall back to libpq env vars.

3. Use it

Ask your agent:

"Create a notebook that generates 100 random numbers, plots a histogram, and adds a markdown summary."

Tools

Session operations accept an optional notebook_path. When omitted, the manager's default notebook is used. Open and close tools require a path.

notebook_open(path) keeps an existing default; use notebook_open(path, set_default=True) to switch subsequent pathless calls. Explicit paths on execution tools affect only that call. Other sessions remain open when switching. notebook_list shows the current default and open notebooks. No session ID is required.

Session management is provided by the core toolkit's NotebookWorkspace, running inside the MCP server process. Local and remote MCP connections use the same behavior. Callers sharing a manager share its default; independent callers should use explicit notebook paths when working through that shared manager.

Notebook Lifecycle

Code Execution

Notebook Document

Cell Reads

Packages

Kernel Control

Introspection

Full tool reference with parameters and examples: Tool reference

Installation

# From PyPI (when published)
uvx mcp-jupyter-notebook

# From PyPI with toolkit DataFrame serialization support
uv pip install "mcp-jupyter-notebook[dataframe]"

# From source
git clone https://github.com/Cyb3rWard0g/mcp-jupyter-notebook.git
cd mcp-jupyter-notebook
uv pip install -e ".[dev]"

Configuration

All settings can be passed as CLI arguments or environment variables. CLI arguments take precedence.

Full configuration reference: docs/mcp-server/configuration.md

MCP_JUPYTER_PREFER_COLLAB remains a compatibility alias when the explicit mode is unset. Session/list results show the selected document transport and a fallback reason. Kernel execution results include stable cell/request identity, persistence status, truncation accounting, and timeout/outcome fields.

Project Structure

src/mcp_jupyter_notebook/
├── __init__.py     # CLI entry point (argparse)
├── server.py       # FastMCP server, lifespan, config processing
├── context.py      # AppContext dataclass (shared lifespan state)
└── tools/          # Tool registrations (notebook + optional domains)
  ├── notebook/       # Core notebook tool pack, split by concern
  └── postgresql.py   # Optional PostgreSQL helper tools

Development

git clone https://github.com/Cyb3rWard0g/mcp-jupyter-notebook.git
cd mcp-jupyter-notebook
uv pip install -e ".[dev]"

# Run tests
uv run pytest

# Lint
uv run ruff check src/ tests/
uv run ruff format src/ tests/

See docs/architecture.md for internals and CONTRIBUTING.md for the release process.

License

Apache License 2.0