Skip to content
Back to search

antigravity-mcp

An MCP server that lets Claude Code and other MCP clients delegate coding work to Google's Antigravity CLI (agy) on your computer: persistent subagents with progress, follow-ups, approvals and Git worktree isolation.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/houyhlouis--antigravity-mcp/badge.svg)](/listings/houyhlouis--antigravity-mcp)

HTML

<a href="/listings/houyhlouis--antigravity-mcp"><img src="/api/listings/houyhlouis--antigravity-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

The steps below use Claude Code. For other clients, see [Step 5](#step-5-connect-your-mcp-client) and [docs/installation.md](docs/installation.md).

Step 1: Install Python

- **Windows:** install Python 3.11+ from [python.org](https://www.python.org/downloads/) and tick **Add python.exe to PATH**. This also installs the `py` launcher 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](https://antigravity.google/docs/getting-started). In short:

macOS / Linux:

curl -fsSL https://antigravity.google/cli/install.sh | bash

Windows (PowerShell):

irm https://antigravity.google/cli/install.ps1 | iex

Then 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 --version

Step 3: Download Antigravity MCP

Get the code from the [antigravity-mcp repository](https://github.com/houyhlouis/antigravity-mcp) 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-mcp

Or download **Source code (zip)** from the [latest release](https://github.com/houyhlouis/antigravity-mcp/releases/latest) 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 doctor

On 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" serve

Windows (PowerShell):

claude mcp add --transport stdio --scope user antigravity -- py -3 "$PWD\server.py" serve

Check 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](examples/mcp.json) and [examples/mcp.windows.json](examples/mcp.windows.json).

Step 6 (optional): Teach your agent the workflow

Copy [examples/CLAUDE.md](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](docs/configuration.md).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 239 lines · 2 findings marked
  1. # Antigravity MCP
  2. **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.**
  3. Antigravity MCP is a small local MCP server. It turns the [Antigravity CLI](https://antigravity.google/product/antigravity-cli) (`agy`) on your computer into persistent coding subagents for your main AI agent:
  4. - **Persistent conversations.** Start a task, follow its progress, send follow-ups, steer or interrupt a running turn, and resume after a restart.
  5. - **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 `/compact` or `/goal`. Your `agy` settings, rules and permission rules apply unchanged.
  6. - **Two-way communication.** When the Antigravity agent asks a question, the main agent answers it.
  7. - **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.
  8. - **Parallel work in Git worktrees.** Give each task its own worktree, then take the result as a reviewable patch.
  9. - **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.
  10. - **No extra dependencies.** Python standard library only. Windows, macOS and Linux, local pipes and sockets only (never a network port).
  11. It uses only interfaces that Google documents for Antigravity CLI: the [Agent Client Protocol server `agy acp`](https://antigravity.google/docs/cli/acp) (the same interface that Zed, JetBrains IDEs and Xcode use) and [headless mode](https://antigravity.google/docs/cli/headless). It never touches your Google sign-in. See [Terms of use](#terms-of-use).
  12. ## Contents
  13. - [Requirements](#requirements)
  14. - [Installation](#installation)
  15. - [Your first task](#your-first-task)
  16. - [Approvals and questions](#approvals-and-questions)
  17. - [Terms of use](#terms-of-use)
  18. - [Updating and uninstalling](#updating-and-uninstalling)
  19. - [Troubleshooting](#troubleshooting)
  20. - [How it works](#how-it-works)
  21. - [Documentation](#documentation)
  22. - [Development](#development)
  23. ## Requirements
  24. | You need | Version | Check with |
  25. |---|---|---|
  26. | Python | 3.11 or newer | `python3 --version` (Windows: `py -3 --version`) |
  27. | Antigravity CLI | 1.5.0 or newer (tested with 1.5.13) | `agy --version` |
  28. | An Antigravity sign-in | Google account, Gemini Enterprise, Gemini API key or Google Cloud credentials | run `agy` once |
  29. | An MCP client | Claude Code, Claude Desktop, or another stdio client | |
  30. | Git (only for worktrees) | 2.36 or newer | `git --version` |
  31. **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.
  32. ## Installation
  33. The steps below use Claude Code. For other clients, see [Step 5](#step-5-connect-your-mcp-client) and [docs/installation.md](docs/installation.md).
  34. ### Step 1: Install Python
  35. - **Windows:** install Python 3.11+ from [python.org](https://www.python.org/downloads/) and tick **Add python.exe to PATH**. This also installs the `py` launcher used below.
  36. - **macOS:** `brew install python`, or the installer from python.org.
  37. - **Linux:** your distribution's package, for example `sudo apt install python3`.
  38. ### Step 2: Install and sign in to Antigravity CLI
  39. Follow [Google's quickstart](https://antigravity.google/docs/getting-started). In short:
  40. macOS / Linux:
  41. ```bash
  42. curl -fsSL https://antigravity.google/cli/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 59 on GitHub
  43. ```
  44. Windows (PowerShell):
  45. ```powershell
  46. irm https://antigravity.google/cli/install.ps1 | iex
  47. ```
  48. Then 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:
  49. ```bash
  50. agy --version
  51. ```
  52. ### Step 3: Download Antigravity MCP
  53. Get the code from the [antigravity-mcp repository](https://github.com/houyhlouis/antigravity-mcp) 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.
  54. ```bash
  55. git clone https://github.com/houyhlouis/antigravity-mcp.git
  56. cd antigravity-mcp
  57. ```
  58. Or download **Source code (zip)** from the [latest release](https://github.com/houyhlouis/antigravity-mcp/releases/latest) and extract it. Nothing has to be installed after downloading.
  59. ### Step 4: Check that it works
  60. In the `antigravity-mcp` folder:
  61. ```bash
  62. python3 server.py --version
  63. python3 server.py doctor
  64. ```
  65. On 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.
  66. ### Step 5: Connect your MCP client
  67. **Claude Code.** Run this inside the `antigravity-mcp` folder.
  68. macOS / Linux:
  69. ```bash
  70. claude mcp add --transport stdio --scope user antigravity -- python3 "$PWD/server.py" serve
  71. ```
  72. Windows (PowerShell):
  73. ```powershell
  74. claude mcp add --transport stdio --scope user antigravity -- py -3 "$PWD\server.py" serve
  75. ```
  76. Check with `claude mcp list` or `/mcp` inside Claude Code: `antigravity` should be connected.
  77. **Claude Desktop and other clients.** Add this to the client's MCP configuration and restart it:
  78. ```json
  79. {
  80. "mcpServers": {
  81. "antigravity": {
  82. "command": "python3",
  83. "args": ["/absolute/path/to/antigravity-mcp/server.py", "serve"]
  84. }
  85. }
  86. }
  87. ```
  88. On Windows use `"command": "py"` and `"args": ["-3", "C:\\Tools\\antigravity-mcp\\server.py", "serve"]`. Ready-made files: [examples/mcp.json](examples/mcp.json) and [examples/mcp.windows.json](examples/mcp.windows.json).
  89. ### Step 6 (optional): Teach your agent the workflow
  90. Copy [examples/CLAUDE.md](examples/CLAUDE.md) into your project's `CLAUDE.md` (or your agent's instructions). It explains polling, questions, approvals and worktrees.
  91. No configuration file is needed. Optional settings are described in [docs/configuration.md](docs/configuration.md).
  92. ## Your first task
  93. Ask your main agent in plain language:
  94. ```text
  95. Use Antigravity in this project to find out why the tests fail and fix them.
  96. Keep me updated and answer its questions.
  97. ```
  98. ```text
  99. Start two Antigravity tasks in separate worktrees: one tries approach A, the
  100. other approach B. Show me both patches when they are done.
  101. ```
  102. ```text
  103. Continue the same Antigravity conversation: add a --json flag and run the tests again.
  104. ```
  105. 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](docs/usage.md).
  106. ## Approvals and questions
  107. Antigravity asks before actions that its [permission rules](https://antigravity.google/docs/permissions) do not allow, for example most terminal commands in `default` mode. The server turns each prompt into a pending request:
  108. | Who | May |
  109. |---|---|
  110. | The main agent | Always **deny**. Answer the Antigravity agent's **questions** |
  111. | You | **Allow** or deny, in your MCP client's prompt (`agy_review_request`) or in a terminal: `python3 server.py review REQUEST_ID` |
  112. | Antigravity's Auto mode (`mode: "auto"`) | Let Antigravity's own reviewer decide, where Antigravity offers Auto mode |
  113. The main agent can approve only if you set `approval_relay = true` in the [settings file](docs/configuration.md). The server never uses `--dangerously-skip-permissions`. To get fewer prompts, add allow rules in Antigravity (`/permissions`) or use `mode: "accept-edits"`.
  114. ## Terms of use
  115. You use Antigravity under [Google's terms](https://antigravity.google/terms), and you are responsible for what the agents you start do. This project is designed to stay inside them:
  116. - It runs only the official `agy` program through interfaces that Google documents for third-party clients ("Any ACP client can launch Antigravity CLI"), and identifies itself honestly as `antigravity-mcp`.
  117. - It never reads, copies or uses your sign-in token, never calls Google's services directly, and never signs in or out for you.
  118. - It respects Antigravity's permission engine and your account limits (see [Limitations](docs/limitations.md)).
  119. 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](https://discuss.ai.google.dev/c/antigravity/64). This project is not affiliated with or endorsed by Google.
  120. ## Updating and uninstalling
  121. **Update:** stop the background broker first, then update the files, then restart your MCP client:
  122. ```bash
  123. cd antigravity-mcp
  124. python3 server.py stop
  125. git pull
  126. ```
  127. **Uninstall:** `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.
  128. ## Troubleshooting
  129. | Problem | What to do |
  130. |---|---|
  131. | Anything unclear | `python3 server.py doctor` |
  132. | `agy executable not found` | Make sure `agy --version` works in a new terminal, or set `agy_binary` to its full path in the [settings file](docs/configuration.md) |
  133. | `not_signed_in` | Run `agy` in a terminal on this computer as the same OS account and sign in (over SSH: `agy acp --login`) |
  134. | `quota_exhausted` | Check `agy_usage`; wait for the reset time or choose another model |
  135. | A task stays `waiting` | A question or an approval is pending: list them with `agy_requests`, or run `server.py review REQUEST_ID` |
  136. | A folder stays reserved after a task finished | The task may still have background work or native subagents. See `claims` in `agy_get`; close the task with `agy_close` |
  137. More in [docs/troubleshooting.md](docs/troubleshooting.md).
  138. ## How it works
  139. ```mermaid
  140. flowchart LR
  141. A[Main agent<br/>e.g. Claude Code] <-->|MCP over stdio| B[server.py serve]
  142. B <-->|private local socket / pipe| C[Background broker]
  143. C <-->|ACP over stdio| D["agy acp<br/>(one per task)"]
  144. D --> E[Your project]
  145. ```
  146. 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](docs/architecture.md) and [security](docs/security.md).
  147. ## Documentation
  148. | Guide | What it covers |
  149. |---|---|
  150. | [Installation details](docs/installation.md) | Other MCP clients, Windows and macOS notes, package install |
  151. | [Usage guide](docs/usage.md) | The task workflow, approvals, worktrees, headless runs, recovery |
  152. | [Tool reference](docs/tools.md) | All tools, their arguments, task states and errors |
  153. | [Configuration](docs/configuration.md) | Optional settings file |
  154. | [Troubleshooting](docs/troubleshooting.md) | Common errors and fixes |
  155. | [Security](docs/security.md) | Trust model, approvals, stored data, terms |
  156. | [Architecture](docs/architecture.md) | Components, message flow and guarantees |
  157. | [Limitations](docs/limitations.md) | What is not supported, and why |
  158. | [Development](docs/development.md) | Tests, CI, live checks and releases |
  159. | [Changelog](CHANGELOG.md) | Release notes |
  160. ## Development
  161. ```bash
  162. python3 scripts/run_tests.py
  163. ```
  164. The 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](docs/development.md).
  165. ## License
  166. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.