____ _ _
/ ___| | __ _ _ _ __| | ___
| | | |/ _` | | | |/ _` |/ _ \
| |___| | (_| | |_| | (_| | __/
\____|_|\__,_|\__,_|\__,_|\___|
|
+----+----+
| MCP | (- you are here
+----+----+
|
_ _ _ _ _
/ \ _ __ | |_(_) __ _ _ __ __ ___ _(_) |_ _ _
/ _ \ | '_ \| __| |/ _` | '__/ _` \ \ / / | __| | | |
/ ___ \| | | | |_| | (_| | | | (_| |\ V /| | |_| |_| |
/_/ \_\_| |_|\__|_|\__, |_| \__,_| \_/ |_|\__|\__, |
|___/ |___/
What is this?
mcp-server-google-antigravity is a small MCP (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
curl -fsSL https://antigravity.google/cli/install.sh | bash
Windows (PowerShell)
irm https://antigravity.google/cli/install.ps1 | iex
Windows (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\<you>\AppData\Local\agy\bin\agy.exe |
Sign in and verify:
agy
agy --version
agy models
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:
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):
git clone https://github.com/TurkerYakup/mcp-server-google-antigravity.git
cd mcp-server-google-antigravity
npm install
npm run 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:
{
"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
claude mcp add antigravity -- npx -y mcp-server-google-antigravity
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:
use_antigravity({ prompt: "...", add_dirs: ["C:/Dev/Repos/foo"] }) β returns { "jobId": "mrib1q20_wa5ma1", "status": "running" } instantly.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. |
| 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 snippetjob running β heartbeat every AGY_HEARTBEAT_MS (default 15s) with a tail of the current partial outputjob 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 "<prompt>" and returns when done. Three problems and their fixes:
- 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.
- agy's own print timeout (default 5m). Heavy prompts hit
timeout waiting for response. β every job passes --print-timeout 10m.
- 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 <path> 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.
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.
