jupyter_ai_tools

jupyter_ai_tools is a Jupyter Server extension that exposes a collection of powerful, agent-friendly tools for interacting with notebooks and Git repositories. It is designed for use by AI personas (like those in Jupyter AI) to programmatically modify notebooks, manage code cells, and interact with version control systems.

✨ Features

This extension provides runtime-discoverable tools compatible with OpenAI-style function calling or MCP tool schemas. These tools can be invoked by agents to:

🧠 Notebook Tools (nb_toolkit)

• read_notebook: Read entire notebook contents as markdown
• read_cell: Read a specific notebook cell by index
• add_cell: Add a new cell to a notebook
• insert_cell: Insert a cell at a specific index in the notebook
• delete_cell: Remove a cell from the notebook
• edit_cell: Modify a cell's content
• get_cell_id_from_index: Get a cell ID from its one-based number shown in JupyterLab
• create_notebook: Create a new Jupyter notebook

🌀 Git Tools (git_toolkit)

• git_clone: Clone a Git repository to a specified path
• git_status: Get the current working tree status
• git_log: View recent commit history
• git_pull: Pull changes from remote repository
• git_push: Push local changes to remote branch
• git_commit: Commit staged changes with a message
• git_add: Stage files for commit (individually or all)
• git_get_repo_root: Get the root directory of the Git repository

These tools are ideal for agents that assist users with code editing, version control, or dynamic notebook interaction.

🔧 Creating Collaborative Tools

For developers building AI tools that need collaborative awareness, jupyter_ai_tools provides a collaborative_tool decorator that automatically enables real-time collaboration features.

This decorator enables other users in the same Jupyter environment to see when your AI tool is actively working on shared notebooks, improving the collaborative experience.

from jupyter_ai_tools.utils import collaborative_tool

# Define user information
user_info = {
    "name": "Alice",
    "color": "var(--jp-collaborator-color1)",
    "display_name": "Alice Smith"
}

# Apply collaborative awareness to your tool
@collaborative_tool(user=user_info)
async def my_notebook_tool(file_path: str, content: str):
    """Your tool implementation here"""
    # Tool automatically sets user awareness for:
    # - Global awareness system (all users can see Alice is active)
    # - Notebook-specific awareness (for .ipynb files)
    return f"Processed {file_path}"

Requirements

• Jupyter Server

Install

To install the extension, execute:

pip install jupyter_ai_tools

Without a JupyterLab web client

Without a real-time collaboration provider, the notebook tools run in the JupyterLab frontend through jupyterlab-ai-commands. The write tools save the notebook after an edit, so the file on disk matches the notebook in JupyterLab. When the save fails, for example because the file also changed on disk, the result of the tool has a save_error. When no JupyterLab tab is open, nothing holds a live model of the notebook, so the read and write tools (read_notebook, add_cell, insert_cell, delete_cell, edit_cell, ...) read and edit the notebook file on disk instead. The result of a write tool then says that the edit went to the file on disk.

run_cell and run_all_cells with a file_path run the cells in a kernel on the server, and write the outputs to the notebook file on disk. They use the kernel of the notebook session, and start a session if there is none. JupyterLab connects to the same kernel when it opens the notebook.

With write_outputs=False, run_cell and run_all_cells run the cells in the kernel of the notebook and return the outputs, without a change to the notebook. This works with or without a web client, and with or without RTC. The kernel state changes, but JupyterLab does not show the run.

A kernel that these tools start keeps running after the run, as a kernel that JupyterLab starts does.

The tools that need the user interface (select_cell, get_active_notebook, get_active_cell_id, open_file, and run_cell or run_all_cells without a file_path) return the error of jupyterlab-commands-toolkit, which asks to open JupyterLab in a web browser.

Uninstall

To remove the extension, execute:

pip uninstall jupyter_ai_tools

Troubleshoot

If you are seeing the frontend extension, but it is not working, check that the server extension is enabled:

jupyter server extension list

Contributing

Development install

# Clone the repo to your local environment
# Change directory to the jupyter_ai_tools directory
# Install package in development mode - will automatically enable
# The server extension.
pip install -e .

You can watch the source directory and run your Jupyter Server-based application at the same time in different terminals to watch for changes in the extension's source and automatically rebuild the extension. For example, when running JupyterLab:

jupyter lab --autoreload

If your extension does not depend a particular frontend, you can run the server directly:

jupyter server --autoreload

Running Tests

Install dependencies:

pip install -e ".[test]"

Development uninstall

pip uninstall jupyter_ai_tools

Packaging the extension

See RELEASE