antigravity-nb

A Jupyter notebook MCP server for Antigravity — lets AI agents read, edit, and execute .ipynb notebooks directly inside your workspace.

What it does

Exposes 10 tools over the Model Context Protocol (stdio transport)
Antigravity agents can open notebooks, read/edit/insert/delete cells, run them cell-by-cell or as tagged pipeline stages, and restart the kernel
Paths are sandboxed to your workspace root — only .ipynb files are allowed

Install

From GitHub (recommended)

pip install git+https://github.com/Ian747-tw/Antigravity-Jupiter-Notebook-MCP.git

For local development

git clone https://github.com/Ian747-tw/Antigravity-Jupiter-Notebook-MCP.git
cd antigravity-nb
pip install -e .

Add to Antigravity

1. Locate your configuration file

Open your Antigravity configuration file. It is usually found at:

~/.gemini/antigravity/mcp_config.json

Or go to Settings → MCP Servers inside Antigravity.

2. Add the server

Append the following to your mcpServers object:

{
  "mcpServers": {
    "antigravity-nb": {
      "command": "antigravity-nb",
      "args": ["serve-agent", "--workspace-root", "${workspaceFolder}"]
    }
  }
}

3. Reload

Restart Antigravity or trigger Refresh MCP Servers to discover the new tools.

Verify

Ask the agent:

"List the tools available from antigravity-nb" "Open a notebook and run the first cell"

Once connected, Antigravity discovers all 10 tools automatically. You can then ask it things like:

"Run the preprocess stage in pipeline.ipynb and show me the outputs" "Edit cell 2 in analysis.ipynb to use pandas instead of a plain list" "Run all cells in notebook.ipynb and tell me if any failed"

Troubleshooting

Kernel not found / ModuleNotFoundError

If you see ModuleNotFoundError when running a cell, the notebook is executing in a kernel that doesn't have your packages installed. Check available kernels and install one that matches your environment:

# List installed kernels
jupyter kernelspec list

# Install the current environment as a kernel
python -m ipykernel install --user --name myenv

Then pass kernel_name when calling run_cell or run_range, or restart Antigravity and select the correct kernel.

Pipeline tags

To use the run_pipeline tool, tag your cells in the notebook metadata. In JupyterLab: View → Cell Toolbar → Tags, then add a tag like preprocess, train, or eval to each cell.

The agent can then run specific stages in order while maintaining kernel state across them:

"Run the train and eval stages in model.ipynb"

Debug logging

Run the server manually and pipe stderr to a file to see all tool calls and errors:

antigravity-nb serve-agent --workspace-root . 2>debug.log
tail -f debug.log

Available tools

| Tool | Description | |---|---| | open_notebook | Open a notebook and return cell count + pipeline stages | | list_cells | List all cells with index, type, tags, and source preview | | read_cell | Read the full source and outputs of one cell | | edit_cell | Replace a cell's source (auto-checkpoints before editing) | | insert_cell | Insert a new cell at a given index | | delete_cell | Delete a cell (auto-checkpoints before deleting) | | run_cell | Execute one code cell and return outputs | | run_range | Execute a range of cells [start, end] inclusive | | run_pipeline | Execute cells grouped by tag-based pipeline stages | | restart_kernel | Restart the Jupyter kernel, clearing all in-memory state |

Checkpoints

edit_cell and delete_cell write a timestamped backup before making changes:

notebook.checkpoint_20250610_143022.ipynb

Pass checkpoint=false to skip if you don't need it.

CLI

The CLI is also available for scripting:

# Run a single cell
antigravity-nb run-cell notebook.ipynb 3

# Run a range of cells
antigravity-nb run-range notebook.ipynb 2 7

# Run a tagged pipeline
antigravity-nb run-pipeline notebook.ipynb
antigravity-nb run-pipeline notebook.ipynb --stage preprocess --stage train

# Edit a cell from a file
antigravity-nb edit-cell notebook.ipynb 5 --source-file ./new_cell.py

# List pipeline stages
antigravity-nb list-stages notebook.ipynb

# Start the MCP server manually
antigravity-nb serve-agent --workspace-root .

Python API

from antigravity_nb import NotebookAdapter, KernelSession, NotebookRunner

nb = NotebookAdapter("pipeline.ipynb")
ks = KernelSession(nb)
runner = NotebookRunner(nb, ks)

ks.start()
nb.update_cell(0, "print('hello')")
result = runner.run_cell(0)
print(result.outputs)
nb.save()
ks.shutdown()

Security

Only .ipynb files are allowed
All paths are resolved and checked against --workspace-root; any path outside it is rejected
The server runs as the same user that launched it — don't point it at sensitive directories

Requirements

Python 3.10+
jupyter_client >= 8.0.0
A Jupyter kernel installed for your target language (e.g. pip install ipykernel for Python)

License

MIT

MCP Servers