Agent Jupyter Toolkit

A Python toolkit for building agent tools that interact with Jupyter kernels and the Jupyter protocol. This package provides high-level wrappers and abstractions around jupyter_client, jupyter_ydoc, and pycrdt, making it easy to manage kernels, execute code, and build agent-driven workflows for automation, orchestration, and integration with Model Context Protocol (MCP) servers.

Features

Kernel

• Async-first kernel sessions with pluggable transports:
  • Local transport — direct ZMQ communication with local kernel processes
  • Server transport — HTTP REST + WebSocket to remote Jupyter servers
• Code execution with bounded, coalesced streaming callbacks and separate callback diagnostics
• Notebook-compatible output state for deferred clears, display updates, stream coalescing, and bounded output
• Kernel introspection — tab-completion, object inspection, code-completeness checks, and execution history retrieval
• Kernel control — interrupt/restart, query metadata, and capability-gated debugger and subshell workflows
• Ownership-aware lifecycle — normal shutdown preserves attached/borrowed kernels
• Variable management — inspect and set strict JSON values through base64-encoded payloads
• Extensible hooks — pre/post execution and output hooks for instrumentation

Notebook

• Multi-notebook workspaces: NotebookWorkspace manages open sessions and a default notebook from Python. Switching defaults preserves other live sessions. See the workspace API.
• Multiple notebook transports:
  • Local file transport — filesystem-backed notebooks with thread-safe read/write
  • Contents API transport — Jupyter Server-managed notebooks via REST
  • Collaboration transport — real-time multi-client editing via Yjs/CRDT (pycrdt + jupyter_ydoc)
• Cell operations — append, insert, delete, set source, update outputs (full replace and delta)
• In-memory notebook buffer for staged edits with explicit commit
• Local notebook autosave with optional debounced writes
• Change observers — register callbacks for cell mutations, saves, and awareness events
• Validated persistence with atomic stable-cell identity, explicit normalization, and source/persistence conflicts
• Optional batch execution and trust inspection through public nbclient/nbformat APIs

Use Cases

• Build agent tools that execute code in Jupyter kernels
• Integrate Jupyter kernel execution into MCP servers or other orchestration systems
• Automate notebook and code execution for data science, ML, and automation pipelines
• Build collaborative notebook editing experiences with CRDT-based conflict resolution

Installation

Install from PyPI

# Using pip
pip install agent-jupyter-toolkit

# Install optional DataFrame serialization support
pip install agent-jupyter-toolkit[dataframe]

# Include named actions and exportable input schemas (no MCP dependency)
pip install "agent-jupyter-toolkit[actions]"

# Include a managed local Python kernel
pip install agent-jupyter-toolkit[local]

# Include the nbclient batch executor
pip install agent-jupyter-toolkit[batch]

# Or using uv
uv pip install agent-jupyter-toolkit

The local extra installs ipykernel, batch installs nbclient, and dataframe installs pandas/Arrow serialization support. The integration extra is for maintainers running the real Jupyter Server and collaboration tests.

Named actions without MCP

The optional actions extra provides NotebookActions, the same implementations used by the corresponding notebook MCP tools. An application can inspect action descriptions/input schemas and invoke a selected action directly:

from agent_jupyter_toolkit.actions import NotebookActions
from agent_jupyter_toolkit.notebook import NotebookWorkspace

async def investigate():
    async with NotebookWorkspace() as workspace:
        actions = NotebookActions(workspace)
        definitions = actions.definitions()
        await actions.invoke("open", {"notebook_path": "investigation.ipynb"})
        await actions.invoke("code_run", {"code": "value = 21"})
        result = await actions.invoke("code_run", {"code": "print(value * 2)"})
        return result

The explicit action set covers lifecycle, stable-ID document reads/edits, visible code/markdown, packages/dependencies, kernel introspection and JSON variables. invoke rejects unknown actions and validates typed inputs without coercion or automatic retries. Named Python methods remain available for direct integrations. Calls share the workspace's existing sessions; they do not create a new workspace context per action. The embedding application owns authorization, concurrency, deadlines and retention. Saved notebooks do not restore live Python variables. The action layer does not add dataset export or DataFrame serialization to the existing JSON variable getter.

Development (monorepo)

git clone https://github.com/Cyb3rWard0g/agent-jupyter-toolkit.git
cd agent-jupyter-toolkit
uv sync --all-packages --all-extras --dev

This installs both agent-jupyter-toolkit and mcp-jupyter-notebook in editable mode into the .venv.

Quickstart

Local kernel execution does not require a Jupyter Server. The library starts a local kernel process for you (via jupyter_client) and connects over ZMQ.

Basic execution

import asyncio
from agent_jupyter_toolkit.kernel import SessionConfig, create_session


async def main() -> None:
    async with create_session(SessionConfig(mode="local", kernel_name="python3")) as session:
        result = await session.execute(
            "import os\n"
            "from platform import node\n"
            "user = os.environ.get('USER', 'friend')\n"
            "print(f'Hello {user} from {node()}')\n"
        )
    print("status:", result.status)
    print("stdout:", result.stdout.strip())


asyncio.run(main())

Introspection and control

async with create_session() as session:
    # Tab-completion
    result = await session.complete("import os; os.path.jo", cursor_pos=21)
    print(result.matches)  # ["join"]

    # Object inspection
    info = await session.inspect("len", cursor_pos=3)
    print(info.data.get("text/plain", ""))

    # Code-completeness check
    check = await session.is_complete("for i in range(10):")
    print(check.status)  # "incomplete"
    print(check.indent)  # "    "

    # Execution history
    hist = await session.history(n=5)
    for entry in hist.history:
        print(f"[{entry.line_number}] {entry.input}")

    # Kernel metadata
    kinfo = await session.kernel_info()
    print(f"{kinfo.language_info['name']} {kinfo.language_info['version']}")

    # Interrupt a long-running cell
    import asyncio

    task = asyncio.create_task(session.execute("import time; time.sleep(999)"))
    await asyncio.sleep(1)
    await session.interrupt()

For server-backed and notebook scenarios, see the quickstarts/ directory.

API Overview

Kernel Session

Notebook Document Transport

Architecture

agent_jupyter_toolkit
├── kernel/
│   ├── session.py          # Session + create_session() factory
│   ├── transport.py        # KernelTransport protocol
│   ├── types.py            # Dataclasses (SessionConfig, ExecutionResult, ...)
│   ├── manager.py          # KernelManager (lifecycle, channels)
│   ├── messages.py         # Wire-protocol message builders
│   ├── variables.py        # VariableManager (inspect/set kernel vars)
│   ├── hooks.py            # Extensible execution hooks
│   ├── mimetypes.py        # MIME-type serialization registry
│   ├── serialization.py    # High-level serialize/deserialize API
│   └── transports/
│       ├── local.py        # LocalTransport (ZMQ)
│       └── server.py       # ServerTransport (HTTP+WS)
├── notebook/
│   ├── session.py          # NotebookSession (kernel + document orchestration)
│   ├── workspace.py        # Multi-notebook registry, default selection, lifecycle
│   ├── _workspace_files.py # Private local and Contents API file operations
│   ├── transport.py        # NotebookDocumentTransport protocol
│   ├── factory.py          # make_document_transport() factory
│   ├── buffer.py           # In-memory NotebookBuffer
│   ├── cells.py            # Cell creation helpers (code, markdown)
│   ├── config.py           # Environment-based Config (allowlist, timeout)
│   ├── utils.py            # Path validation, output normalization
│   └── transports/
│       ├── local_file.py   # LocalFileDocumentTransport (+ autosave)
│       ├── contents.py     # ContentsApiDocumentTransport
│       └── collab/         # CollabYjsDocumentTransport (Yjs/CRDT)
└── utils/                  # High-level helpers (factories, execution, packages)

Dependencies

See the API reference for execution result fields and optional APIs, and configuration for collaboration modes and local launch options.

Contributing

See CONTRIBUTING.md for dev setup, testing, and the release process.

Contributions and feedback are welcome!