# mcp-server-google-antigravity
**Category:** π» Developer Tools
**Repository:** https://github.com/TurkerYakup/mcp-server-google-antigravity
**Views:** 0
**Installs:** 0
**Upvotes:** 0
**Directory Page:** https://allmcps.com/mcp/mcp-server-google-antigravity
## Description
MCP server exposing Google Antigravity (agy CLI / Gemini): jobs, codebase analysis, file tools.
## Claude Desktop Quick Installation
Heuristic fallback β verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):
```json
"mcpServers": {
"mcp-server-google-antigravity": {
"command": "npx",
"args": ["-y","mcp-server-google-antigravity"]
}
}
```
## Documentation & README
```text
____ _ _
/ ___| | __ _ _ _ __| | ___
| | | |/ _` | | | |/ _` |/ _ \
| |___| | (_| | |_| | (_| | __/
\____|_|\__,_|\__,_|\__,_|\___|
|
+----+----+
| MCP | (- you are here
+----+----+
|
_ _ _ _ _
/ \ _ __ | |_(_) __ _ _ __ __ ___ _(_) |_ _ _
/ _ \ | '_ \| __| |/ _` | '__/ _` \ \ / / | __| | | |
/ ___ \| | | | |_| | (_| | | | (_| |\ V /| | |_| |_| |
/_/ \_\_| |_|\__|_|\__, |_| \__,_| \_/ |_|\__|\__, |
|___/ |___/
```
**Let Claude (or any MCP client) hand its heavy work to Google Antigravity's `agy` agent.**
-4285F4?logo=google&logoColor=white)
---
## What is this?
**mcp-server-google-antigravity** is a small [MCP](https://modelcontextprotocol.io) (Model Context Protocol) server. It exposes **Google Antigravity** β Google's terminal coding agent, driven by the `agy` CLI (Gemini under the hood) β as a set of tools any MCP client can call.
The idea: your primary model (Claude Desktop, Claude Code, Codex, β¦) stays lean and delegates the **grunt work** β web search, whole-repo analysis, scaffolding files, long-running edits β to a second agent running in the background. Jobs are **async and unlimited**: you fire a task, get a `jobId` instantly, and poll for the result while the caller keeps working.
```
Claude / Codex this MCP server Antigravity
+---------------+ tool +----------------+ spawns +--------------+
| "analyze the | -----> | use_antigravity| ------> | agy --print |
| whole repo" | | -> jobId(async)| | (Gemini) |
+---------------+ <----- +----------------+ <------ +--------------+
keeps working polls result / logs does the work
```
---
## Requirements
| Need | Why |
|------|-----|
| **Node.js 18+** | Runs this server (ships with `npx`/`npm`). Check: `node --version` |
| **Antigravity CLI (`agy`)** | The agent this server drives. Install below. |
| An **MCP client** | Claude Desktop, Claude Code, or anything that speaks MCP |
---
## Step 1 β Install the Antigravity CLI (`agy`)
> Never used `agy` before? Start here. It's one command. First launch signs you in with Google.
**macOS / Linux**
```bash
curl -fsSL https://antigravity.google/cli/install.sh | bash
```
**Windows (PowerShell)**
```powershell
irm https://antigravity.google/cli/install.ps1 | iex
```
**Windows (CMD)**
```cmd
curl -fsSL https://antigravity.google/cli/install.cmd -o install.cmd && install.cmd && del install.cmd
```
**Where it lands** (remember this β you may need it for `AGY_PATH` below):
| OS | Default `agy` location |
|----|------------------------|
| macOS / Linux | `~/.local/bin/agy` |
| Windows | `C:\Users\\AppData\Local\agy\bin\agy.exe` |
**Sign in and verify:**
```bash
agy # first run opens a Google Sign-In in your browser (creds cached in your OS keyring)
agy --version # should print a version, e.g. 1.1.1
agy models # lists the models you can use (Gemini 3.5 Flash, Gemini 3.1 Pro, ...)
```
If `agy` isn't found afterwards, open a new terminal (so `PATH` reloads) or run `agy install` to fix shell paths.
---
## Step 2 β Get this MCP server
**Option A β npx (recommended):** Skip straight to Step 3 and use the `npx` config. The `npx` path works seamlessly from the public npm registry with no authentication required.
Alternatively, you can install the package globally:
```bash
npm install -g mcp-server-google-antigravity
```
This exposes the `mcp-server-google-antigravity` command (which you can register directly in your MCP client's config instead of `npx`).
**Option B β from source** (for hacking on it):
```bash
git clone https://github.com/TurkerYakup/mcp-server-google-antigravity.git
cd mcp-server-google-antigravity
npm install
npm run check # quick syntax check
```
> `node-pty` (used only for clean output on Windows) is an **optional** dependency β if it can't build on macOS/Linux the install still succeeds and the server falls back automatically. No compiler needed.
---
## Step 3 β Register it with your MCP client
Claude Desktop
Edit your `claude_desktop_config.json`:
| OS | Config file |
|----|-------------|
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| Linux | `~/.config/Claude/claude_desktop_config.json` |
**Using npx (Option A) β recommended:**
```json
{
"mcpServers": {
"antigravity": {
"command": "npx",
"args": ["-y", "mcp-server-google-antigravity"],
"env": {
"AGY_MODEL": "Gemini 3.5 Flash (Medium)",
"AGY_AUTO_APPROVE": "true"
},
"timeout": 900000
}
}
}
```
> **Windows note:** Electron (Claude Desktop) often can't spawn `npx` directly β if the server fails to start, wrap it in `cmd`: set `"command": "cmd"` and `"args": ["/c", "npx", "-y", "mcp-server-google-antigravity"]` (keep the same `env`/`timeout`).
**From source (Option B):** set `"command": "node"` and `"args": ["/absolute/path/to/mcp-server-google-antigravity/index.js"]` instead. On **Windows** use forward slashes, e.g. `"C:/path/to/mcp-server-google-antigravity/index.js"`.
Restart the app fully after editing (quit from the tray/menu bar, not just close the window).
Claude Code (CLI) β works on macOS, Windows, Linux
```bash
# npx (Option A)
claude mcp add antigravity -- npx -y mcp-server-google-antigravity
# from source (Option B)
claude mcp add antigravity -- node /absolute/path/to/mcp-server-google-antigravity/index.js
```
That's it. Your client now has tools like `use_antigravity`, `antigravity_continue`, and the filesystem helpers.
---
## Quick example
Ask your MCP client something like *"use antigravity to analyze the repo at C:/Dev/Repos/foo and summarize its architecture"*. Under the hood the client calls:
1. `use_antigravity({ prompt: "...", add_dirs: ["C:/Dev/Repos/foo"] })` β returns `{ "jobId": "mrib1q20_wa5ma1", "status": "running" }` **instantly**.
2. `antigravity_result({ jobId, wait_ms: 10000 })` β blocks/long-polls until the job is done or the 10-second wait elapses. While still running, it returns a lean payload containing status, character count, and the last 200 characters of output (`{ status, jobId, chars, tail, startedAt }`). Once complete, it returns the full record (including `durationMs` and `bytes` telemetry).
Follow up in the same session with `antigravity_continue({ prompt: "now list the top 3 risks" })`. Need agy to write files? Pass `add_dirs` so it has a workspace; `auto_approve` (default) lets it create/edit without prompts.
---
## Configuration (environment variables)
Everything is optional β sane defaults out of the box.
| Var | Default | What it does |
|-----|---------|--------------|
| `AGY_PATH` | auto-detected | Full path to the `agy` binary. Only needed if it's not on `PATH`. On Windows the path is auto-collapsed to an 8.3 short path, so a non-ASCII username no longer breaks anything. |
| `AGY_MODEL` | agy's default | Default model when a call omits `model`. Use the exact name from `agy models`, e.g. `Gemini 3.5 Flash (Medium)`. |
| `AGY_AUTO_APPROVE` | `true` | Pass `--dangerously-skip-permissions` so headless jobs don't hang on a prompt. Set `false` for read-only. |
| `AGY_SANDBOX` | `false` | Run every job with `--sandbox` (terminal-restricted). Cheap; safer for untrusted prompts. Per-call `sandbox` overrides. |
| `AGY_PRINT_TIMEOUT` | `10m` | agy's `--print-timeout`. |
| `AGY_HEARTBEAT_MS` | `15000` | Interval for the "job running" progress notification. `0` disables. |
| `AGY_MODEL_TTL_MS` | `300000` | How long the cached `agy models` list is trusted. |
---
## Tools
| Tool | What it does |
|------|--------------|
| `use_antigravity` | Delegate a task (async). Returns a `jobId` immediately. Params: `prompt`, `thinking_depth` (low/high), `add_dirs` (folders agy may read/write), `auto_approve`, `new_project`, `model`, `mode` (plan/accept-edits), `agent`, `project`, `sandbox`, `write_to_file`, `extract` (optional `"last_code_block"` to extract the last code block to the `extracted` field on the record). |
| `antigravity_continue` | Continue the previous conversation (or a specific `conversation_id`) with a new prompt. |
| `antigravity_result` | Get a job's result by `jobId`. Supports long-polling via optional `wait_ms` and `poll_interval_ms`. While running, returns a lean payload (`{ status, jobId, chars, tail, startedAt }`). On done/error, returns full record (including `durationMs` and `bytes` telemetry). |
| `antigravity_jobs` | List recent jobs and statuses. |
| `antigravity_cancel` | Kill a running job by `jobId`. |
| `antigravity_cleanup` | Delete old job files by age (`older_than_hours`). |
| `antigravity_create_folder` | Create a folder (recursive), done directly by the server. |
| `antigravity_create_file` | Create/write a text file (creates parent dirs); `overwrite:false` to protect existing. |
| `antigravity_create_tree` | Build a whole folder/file tree from a JSON spec. |
| `antigravity_read_file` | Read a UTF-8 text file (instant); optional `max_bytes` cap. |
| `antigravity_list_dir` | List a folder's entries. |
| `antigravity_models` | List available models (`agy models`). |
| `antigravity_agents` | List available agent profiles (`agy agents`). |
| `antigravity_health` | Check that `agy` is reachable + report effective defaults. **Run this first when something's off.** |
The server-side filesystem tools use Node's `fs` directly β instant, and never gated by a permission prompt.
---
## Live progress notifications
Because jobs return a `jobId` immediately, the server pushes MCP **logging notifications** (`notifications/message`, logger `antigravity`) so the client can see activity without polling:
- `job started` β jobId, kind, prompt snippet
- `job running` β heartbeat every `AGY_HEARTBEAT_MS` (default 15s) with a tail of the current partial output
- `job done` / `job failed` β final status, byte count / error
Best-effort: if the client didn't negotiate the `logging` capability they're silently dropped. Polling `antigravity_result` works either way.
---
## How it works (design notes)
The `agy` CLI runs a single prompt with `agy --print ""` and returns when done. Three problems and their fixes:
1. **MCP client request timeout (~60s).** Long tasks made the client give up even though `agy` kept running. β **Async job pattern:** `use_antigravity` spawns `agy` in the background, returns a `jobId` instantly, writes the result to a JSON file in the OS temp dir (`agy_jobs/`), and the client polls `antigravity_result`. Optional long-polling (`wait_ms`) lets clients wait inside the request when short runs are expected. No request ever blocks.
2. **agy's own print timeout (default 5m).** Heavy prompts hit `timeout waiting for response`. β every job passes `--print-timeout 10m`.
3. **Headless file-permission gate.** In `--print` mode agy's file-writes get denied by the "ask" policy and the job hangs. β `auto_approve` (default true) passes `--dangerously-skip-permissions`; `add_dirs` passes `--add-dir ` for the workspace it needs.
---
## Security note
`auto_approve` defaults to **true** (`--dangerously-skip-permissions`) β agy will create/edit files and run terminal commands without prompting. This is intentional: in headless `--print` mode agy otherwise blocks on a permission prompt and the job hangs. For untrusted prompts, prefer `sandbox: true` (terminal-restricted, cheap β a permission layer, not a VM) over turning auto-approve off. Use `auto_approve: false` only for genuinely read-only asks.
---
## Platform support
Fully cross-platform β **macOS, Windows, and Linux**. Windows gets a `node-pty` path for clean streaming (with an automatic fallback if it's unavailable) and auto 8.3 short-path resolution for non-ASCII usernames; macOS/Linux use plain `child_process`. The only per-OS difference is where `agy` lives and where your client's config file is (both covered above).
---
## Troubleshooting
| Symptom | Fix |
|---------|-----|
| `agy not found` / server won't start | Open a **new** terminal so `PATH` reloads, or run `agy install`. Still stuck? Set `AGY_PATH` to the full binary path (Step 1 table). The `antigravity_health` tool confirms whether the server sees `agy`. |
| Job stays `running` forever | agy is probably waiting on a permission prompt. Keep `auto_approve` at its default `true` (headless mode hangs otherwise). Watch progress via `antigravity_jobs` or the job's `partial` field. |
| `Model '...' was not found` warning | Advisory only β the job still runs. Use the **exact** name from `antigravity_models` (they contain spaces, e.g. `Gemini 3.5 Flash (Medium)`). |
| Windows: path breaks on a non-ASCII username | Handled automatically β the server resolves `agy` to its 8.3 short path. No action needed. |
| First run wants you to sign in | Run `agy` once in a terminal to finish the Google Sign-In; credentials are then cached in your OS keyring. |
| Client reports "tool timed out" | Raise the client's own `timeout` (e.g. `900000` ms in Claude Desktop). Jobs are async so the call returns instantly, but some clients still enforce a ceiling. |
---
## License
MIT Β© TΓΌrker Yakup AltΔ±nsoy.