mcp-jupyter-notebook 0.3.0

An MCP server for AI agents to interact with Jupyter notebooks

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

• 17 MCP tools — code execution, markdown, packages, kernel control, introspection, variables
• 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
• 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.

3. Use it

Ask your agent:

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

---

Tools

Code Execution

Tool	Description
notebook_code_run	Append a new code cell, execute it, and return outputs (stdout, stderr, rich displays)
notebook_code_run_existing	Replace the source of an existing cell (by index) and re-execute it
notebook_code_execute	Execute code in the kernel without creating a notebook cell (background work)
notebook_cells_run	Execute multiple cells sequentially (code and/or markdown)

Notebook Document

Tool	Description
notebook_markdown_add	Append a markdown cell to the notebook
notebook_read	Read all cells, sources, outputs, and metadata
notebook_cell_delete	Delete a cell by its 0-based index

Packages

Tool	Description
notebook_packages_install	Install Python packages in the kernel (pip-style specifiers)
notebook_packages_check	Check which packages are available without installing

Kernel Control

Tool	Description
notebook_kernel_interrupt	Interrupt a running computation (SIGINT)
notebook_kernel_info	Get kernel metadata (protocol version, language info, banner)
notebook_session_info	Get session info (kernel type, alive status, connections)

Introspection

Tool	Description
notebook_inspect	Inspect an object — returns docs, type info, docstrings
notebook_complete	Get tab-completion suggestions at a cursor position
notebook_variables_list	List user-defined variables in the kernel's global scope
notebook_variable_get	Get the value of a specific variable
notebook_variable_set	Set a variable in the kernel's global scope

Full tool reference with parameters and examples: docs/tools.md

---

Installation

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

# 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.

Variable	CLI Flag	Description	Default
MCP_JUPYTER_SESSION_MODE	--mode	server (remote Jupyter) or local	server
MCP_JUPYTER_BASE_URL	--base-url	Jupyter server URL	—
MCP_JUPYTER_TOKEN	--token	Jupyter API token	—
MCP_JUPYTER_KERNEL_NAME	--kernel-name	Kernel spec name	python3
MCP_JUPYTER_NOTEBOOK_PATH	--notebook-path	Notebook file path (.ipynb)	auto-generated
MCP_JUPYTER_TRANSPORT	--transport	stdio, sse, streamable-http	stdio
MCP_JUPYTER_HOST	--host	Host for HTTP transports	127.0.0.1
MCP_JUPYTER_PORT	--port	Port for HTTP transports	8000
MCP_JUPYTER_LOG_LEVEL	—	DEBUG, INFO, WARNING, ERROR	INFO
MCP_JUPYTER_HEADERS_JSON	—	Extra HTTP headers as JSON object	—
MCP_JUPYTER_PREFER_COLLAB	—	Use Yjs real-time sync (true/false)	true

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

---

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.py        # All 17 MCP tool definitions

---

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