Antigravity MCP
Drives Google's Antigravity CLI (agy) on the local machine through its documented Agent Client Protocol server and headless mode, turning it into persistent coding subagents: start a task, poll its progress, send follow-ups, steer or interrupt a turn, answer the Antigravity agent's questions, relay permission approvals to the user, and run parallel tasks in Git worktrees to get reviewable patches. Respects the user's Antigravity settings, models, modes, permission rules and quota, and can report remaining usage.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Antigravity MCP
Let Claude Code (or another MCP client) hand coding work to Google's Antigravity CLI on your computer, and keep a two-way conversation with it.
Antigravity MCP is a small local MCP server. It turns the Antigravity CLI (agy) on your computer into persistent coding subagents for your main AI agent:
Persistent conversations. Start a task, follow its progress, send follow-ups, steer or interrupt a running turn, and resume after a restart.
Feels like
agy. The same models, thinking levels, modes (default,accept-edits,plan, and Auto where Antigravity offers it), custom agents, skills and slash commands such as/compactor/goal. Youragysettings, rules and permission rules apply unchanged.Two-way communication. When the Antigravity agent asks a question, the main agent answers it.
Safe approvals. Antigravity's permission engine decides what needs approval. Nothing is approved silently: approvals go to you, or to Antigravity's own Auto mode if you choose it. The main agent may always deny.
Parallel work in Git worktrees. Give each task its own worktree, then take the result as a reviewable patch.
Account-friendly. Shows your remaining quota, never retries a failed turn on its own, and runs at most four Antigravity sessions at once by default.
No extra dependencies. Python standard library only. Windows, macOS and Linux, local pipes and sockets only (never a network port).
It uses only interfaces that Google documents for Antigravity CLI: the Agent Client Protocol server agy acp (the same interface that Zed, JetBrains IDEs and Xcode use) and headless mode. It never touches your Google sign-in. See Terms of use.
Contents
Related MCP server: worker-mcp
Requirements
You need | Version | Check with |
Python | 3.11 or newer |
|
Antigravity CLI | 1.5.0 or newer (tested with 1.5.13) |
|
An Antigravity sign-in | Google account, Gemini Enterprise, Gemini API key or Google Cloud credentials | run |
An MCP client | Claude Code, Claude Desktop, or another stdio client | |
Git (only for worktrees) | 2.36 or newer |
|
Antigravity CLI must be installed and signed in on the same computer and under the same OS account that runs the MCP server. The server starts agy as that account, and agy uses the sign-in cached there.
Installation
The steps below use Claude Code. For other clients, see Step 5 and docs/installation.md.
Step 1: Install Python
Windows: install Python 3.11+ from python.org and tick Add python.exe to PATH. This also installs the
pylauncher used below.macOS:
brew install python, or the installer from python.org.Linux: your distribution's package, for example
sudo apt install python3.
Step 2: Install and sign in to Antigravity CLI
Follow Google's quickstart. In short:
macOS / Linux:
curl -fsSL https://antigravity.google/cli/install.sh | bashWindows (PowerShell):
irm https://antigravity.google/cli/install.ps1 | iexThen open a new terminal, run agy once and sign in. Over SSH, agy prints a link and asks for a code; alternatively run agy acp --login. Check:
agy --versionStep 3: Download Antigravity MCP
Get the code from the antigravity-mcp repository and keep the folder in a permanent place (for example ~/tools/antigravity-mcp or C:\Tools\antigravity-mcp), because your MCP client runs the server from there.
git clone https://github.com/houyhlouis/antigravity-mcp.git
cd antigravity-mcpOr download Source code (zip) from the latest release and extract it. Nothing has to be installed after downloading.
Step 4: Check that it works
In the antigravity-mcp folder:
python3 server.py --version
python3 server.py doctorOn Windows use py -3 instead of python3. doctor checks Python, the agy executable and its version, ACP support and the state folder. It starts nothing and uses no quota.
Step 5: Connect your MCP client
Claude Code. Run this inside the antigravity-mcp folder.
macOS / Linux:
claude mcp add --transport stdio --scope user antigravity -- python3 "$PWD/server.py" serveWindows (PowerShell):
claude mcp add --transport stdio --scope user antigravity -- py -3 "$PWD\server.py" serveCheck with claude mcp list or /mcp inside Claude Code: antigravity should be connected.
Claude Desktop and other clients. Add this to the client's MCP configuration and restart it:
{
"mcpServers": {
"antigravity": {
"command": "python3",
"args": ["/absolute/path/to/antigravity-mcp/server.py", "serve"]
}
}
}On Windows use "command": "py" and "args": ["-3", "C:\\Tools\\antigravity-mcp\\server.py", "serve"]. Ready-made files: examples/mcp.json and examples/mcp.windows.json.
Step 6 (optional): Teach your agent the workflow
Copy examples/CLAUDE.md into your project's CLAUDE.md (or your agent's instructions). It explains polling, questions, approvals and worktrees.
No configuration file is needed. Optional settings are described in docs/configuration.md.
Your first task
Ask your main agent in plain language:
Use Antigravity in this project to find out why the tests fail and fix them.
Keep me updated and answer its questions.Start two Antigravity tasks in separate worktrees: one tries approach A, the
other approach B. Show me both patches when they are done.Continue the same Antigravity conversation: add a --json flag and run the tests again.Behind the scenes the main agent starts work with agy_start, polls agy_events until the turn ends, answers questions with agy_respond, shows approvals to you with agy_review_request, and reads the result with agy_get. See the usage guide.
Approvals and questions
Antigravity asks before actions that its permission rules do not allow, for example most terminal commands in default mode. The server turns each prompt into a pending request:
Who | May |
The main agent | Always deny. Answer the Antigravity agent's questions |
You | Allow or deny, in your MCP client's prompt ( |
Antigravity's Auto mode ( | Let Antigravity's own reviewer decide, where Antigravity offers Auto mode |
The main agent can approve only if you set approval_relay = true in the settings file. The server never uses --dangerously-skip-permissions. To get fewer prompts, add allow rules in Antigravity (/permissions) or use mode: "accept-edits".
Terms of use
You use Antigravity under Google's terms, and you are responsible for what the agents you start do. This project is designed to stay inside them:
It runs only the official
agyprogram through interfaces that Google documents for third-party clients ("Any ACP client can launch Antigravity CLI"), and identifies itself honestly asantigravity-mcp.It never reads, copies or uses your sign-in token, never calls Google's services directly, and never signs in or out for you.
It respects Antigravity's permission engine and your account limits (see Limitations).
Google's Additional Terms of Service for Antigravity also say that "using third party software, tools, or services to access the Service (e.g. using OpenClaw with Antigravity OAuth) is a breach of this Agreement". This project does not use your Antigravity OAuth sign-in at all; it drives the official CLI the way a supported editor does. Read the terms yourself and decide whether your use is covered. If in doubt, ask Google in the Antigravity forum. This project is not affiliated with or endorsed by Google.
Updating and uninstalling
Update: stop the background broker first, then update the files, then restart your MCP client:
cd antigravity-mcp
python3 server.py stop
git pullUninstall: python3 server.py stop, remove the server from your client (claude mcp remove antigravity --scope user), delete the folder, and optionally the state folder (~/.local/state/antigravity-mcp on macOS/Linux, %LOCALAPPDATA%\AntigravityMCP on Windows). Antigravity's own conversations stay in Antigravity.
Troubleshooting
Problem | What to do |
Anything unclear |
|
| Make sure |
| Run |
| Check |
A task stays | A question or an approval is pending: list them with |
A folder stays reserved after a task finished | The task may still have background work or native subagents. See |
More in docs/troubleshooting.md.
How it works
flowchart LR
A[Main agent<br/>e.g. Claude Code] <-->|MCP over stdio| B[server.py serve]
B <-->|private local socket / pipe| C[Background broker]
C <-->|ACP over stdio| D["agy acp<br/>(one per task)"]
D --> E[Your project]The MCP server that your client starts is a thin adapter. A background broker owns the agy processes, stores tasks and events in a private SQLite database, and keeps running when the client disconnects, so a reconnecting client can catch up. See architecture and security.
Documentation
Guide | What it covers |
Other MCP clients, Windows and macOS notes, package install | |
The task workflow, approvals, worktrees, headless runs, recovery | |
All tools, their arguments, task states and errors | |
Optional settings file | |
Common errors and fixes | |
Trust model, approvals, stored data, terms | |
Components, message flow and guarantees | |
What is not supported, and why | |
Tests, CI, live checks and releases | |
Release notes |
Development
python3 scripts/run_tests.pyThe offline suite uses a simulated agy and no quota. CI runs it on Windows, macOS and Linux with Python 3.11 and 3.14. See docs/development.md.
License
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Source-checked CLI guides and model-aware planning for Claude Code, Codex, and Grok Build.
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Persistent context for Claude. Your AI always knows your projects and next actions across sessions.
Persistent cloud workspaces for AI agents: run commands, edit files, use git and a browser.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables Claude to create, manage, and clean up git worktrees automatically, including dependency installation and GitHub PR creation.5MIT
- FlicenseNot gradedqualityDmaintenanceEnables Claude to delegate coding tasks to a worker CLI, handling actual code modifications and command execution while Claude supervises and verifies results.-
- AlicenseNot gradedqualityCmaintenanceTurns Claude Code into an engineering project manager by orchestrating feature development with isolated Git worktrees, structured task validation, and approval-gated integration.1MIT
- AlicenseNot gradedqualityCmaintenanceLets Codex delegate coding and repository work to an installed Claude Code CLI with permission-aware inspect/write access, model and effort selection, resumable and cloud-attached sessions, and durable synchronous or asynchronous jobs.MIT