Skip to main content
Glama

agycli-mcp

A dependency-free MCP server for the Google Antigravity CLI (agy). It lets Claude Code (or any MCP client) hand work to agy in three explicit modes:

Mode

What agy may do

How it is enforced

plan

Read and search files, then write an implementation plan

Locked by agy's own --mode plan: file edits and shell commands are denied. Returns implementation_plan.md.

ask

Read files and answer

Instruction only: a read-only preamble, plus change detection that reports any files that changed during the run

edit

Read, write and run commands in the workspace

Nothing; use it when you mean it

On top of that: background jobs that survive client disconnects, quota checks, a completion-wake hook for Claude Code, and a doctor command.

  • Pure Node.js 18+, no npm install, no build step: clone and run node agycli-mcp.mjs.

  • macOS, Windows and Linux from one file.

  • MIT licence.

Why another agy MCP server?

tphakala/agy-mcp is excellent and inspired most of the job, quota and hook design here. It always runs agy with --dangerously-skip-permissions --disable-slash-commands, which also disables agy's plan mode, so it has no locked read-only path. agycli-mcp adds the plan / ask / edit split, aimed at a plan-first workflow:

  1. plan: agy studies the code and writes a plan, without touching files.

  2. You review and approve the plan.

  3. edit with the same conversation_id: agy implements the approved plan.

Related MCP server: Antigravity Worker MCP

Requirements

  • Node.js 18 or newer.

  • The Antigravity CLI (agy), signed in. Run agy once interactively to sign in. Tested with agy 1.5.12 on macOS.

  • Git (optional, used for change detection in ask and edit).

Install

git clone https://github.com/bangya96/agycli-mcp.git
cd agycli-mcp
node agycli-mcp.mjs doctor

doctor checks Node, finds agy, checks your sign-in, and verifies the directories. Fix anything marked [FAIL].

Claude Code

macOS / Linux:

claude mcp add agycli -- node /absolute/path/to/agycli-mcp/agycli-mcp.mjs

Windows (PowerShell):

claude mcp add agycli -- node C:\path\to\agycli-mcp\agycli-mcp.mjs

Or in any MCP client config:

{
  "mcpServers": {
    "agycli": { "command": "node", "args": ["/absolute/path/to/agycli-mcp/agycli-mcp.mjs"] }
  }
}

Optional: Claude Code skill

skills/agycli/SKILL.md teaches Claude when to use each mode and which model to pick. Copy it to ~/.claude/skills/agycli/SKILL.md (Windows: %USERPROFILE%\.claude\skills\agycli\SKILL.md).

Optional: completion-wake hook (Claude Code)

Claude Code does not wake the model when a background MCP job finishes. This hook does: after every agy_run, it waits for the job in the background and wakes Claude when the job ends (unless the result was already read). Add to ~/.claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "mcp__agycli__agy_run(_sync)?",
        "hooks": [
          {
            "type": "command",
            "command": "node /absolute/path/to/agycli-mcp/agycli-mcp.mjs hook-wait",
            "asyncRewake": true,
            "timeout": 3700
          }
        ]
      }
    ]
  }
}
  • The agycli in the matcher must match the name you used in claude mcp add.

  • The hook's timeout (seconds) must exceed hook-wait's own limit (1 hour by default, --timeout-ms or AGYCLI_MCP_HOOK_TIMEOUT_MS to change).

  • Hooks run with your shell environment, not the MCP server's. If you set AGYCLI_MCP_STATE_DIR for the server, set it for the hook too.

Tools

Tool

Purpose

agy_run

Start a job in the background; returns job_id (and conversation_id once agy reports it)

agy_run_sync

Start and wait inline up to about 90 s; returns the result or a running job_id

agy_wait

Block until a job finishes (up to about 90 s per call)

agy_status

State and result of a job

agy_cancel

Cancel a job and its whole process tree

agy_jobs

Recent jobs, newest first

agy_usage

Quota per group (weekly and 5-hour windows), level ok / low / critical / exhausted / unknown. Spends no model quota

agy_models

Model ids for the model parameter, with labels and quota groups

Run parameters: prompt (required), mode (plan / ask / edit, default ask), model, effort (low / medium / high / xhigh), cwd (absolute), dirs (extra absolute dirs), conversation_id, timeout_ms (10 s to 2 h, default 20 min), idempotency_key.

The inline wait is capped at 90 s because MCP clients such as Claude Code give up on a tool call after roughly 120 s. Jobs keep running regardless; collect them with agy_wait or agy_status.

Results

A finished job reports state (done, failed, cancelled) and, when it failed, a failure_reason: quota_exhausted, timeout, auth_required, spawn_failed, agy_error, background_aborted, plan_incomplete, interrupted or unknown. partial: true means the text was reconstructed from streamed output and may be incomplete. ask and edit jobs include changes: the files that changed during the run (via git), or null when that could not be checked.

Safety notes

  • plan is the only hard lock. It relies on agy's plan mode. agy still loads the project's AGENTS.md, hooks and its own MCP servers, which run outside that lock.

  • ask is not a sandbox. agy in headless mode writes files and runs commands even without --dangerously-skip-permissions, and --sandbox does not stop writes in the workspace (measured with agy 1.5.12). ask relies on a read-only instruction and then tells you what changed. Run it in a git repository so changes are visible and reversible.

  • edit can do anything your user account can do inside and around the workspace.

  • Only one ask or edit job runs per workspace, and one job per conversation, at a time.

  • Prompts and agy output are stored in the job state directory (see below) for 24 hours.

Terms of Service

agy is a Google product for your own use. Google's suspension appeal form lists "using third party software, tools, or services to access Antigravity" and "resale of AI Developer Tools services" as grounds for suspension. This server only runs the official agy binary through its documented headless mode, but whether that is acceptable is Google's call, not ours. Use your own account, for your own work, at your own risk. Do not use this to resell or share access.

Configuration

Variable

Default

Meaning

AGYCLI_MCP_AGY_PATH

auto

Path to the agy binary

AGYCLI_MCP_APP_DATA_DIR

~/.gemini/antigravity-cli

agy's data dir; plan files are read from brain/<conversation_id>/

AGYCLI_MCP_STATE_DIR

~/.local/state/agycli-mcp, Windows %LOCALAPPDATA%\agycli-mcp

Job state

AGYCLI_MCP_DEFAULT_MODEL

agy's default

Model id used when a run names none

AGYCLI_MCP_TIMEOUT_MS

1200000

Default job timeout

AGYCLI_MCP_SYNC_WAIT_MS

90000

Inline wait cap for agy_run_sync / agy_wait

AGYCLI_MCP_MAX_CONCURRENCY

3

Running jobs per state dir

AGYCLI_MCP_JOB_TTL_MS

86400000

Finished jobs are deleted after this

AGYCLI_MCP_MAX_OUTPUT

200000

Max characters of text returned

AGYCLI_MCP_HOOK_TIMEOUT_MS

3600000

hook-wait limit

AGYCLI_MCP_DEBUG

off

1 logs to stderr

agy is looked up in AGYCLI_MCP_AGY_PATH, then PATH, then the usual install locations (~/.local/bin/agy, ~/.gemini/bin/agy; on Windows %LOCALAPPDATA%\agy\bin\agy.exe, %LOCALAPPDATA%\Antigravity\agy.exe, %USERPROFILE%\.gemini\bin\agy.exe and the Chocolatey shim).

Tested

  • Real agy 1.5.12 on macOS, through the MCP server: doctor, agy_usage, agy_models, an ask job (no files changed), a plan job (plan returned, working tree untouched) and an edit job that continued the plan's conversation and implemented it (changed file reported).

  • The automated suite (fake agy) runs in CI on Linux, macOS and Windows with Node 18 and 22.

Windows status

Windows is supported in code (process-tree kill with taskkill /T /F, .exe lookup, no shell spawning) and the test suite runs on Windows in CI with a fake agy. It has not yet been smoke-tested against a real agy on Windows, and agy's Windows install and data paths come from third-party guides. If plan files are not found, set AGYCLI_MCP_APP_DATA_DIR. Reports welcome.

Prompts are passed on the command line, which Windows limits to about 32 000 characters; longer prompts are refused with a clear error. Put long context in a file and reference its path.

Development

npm test            # or: node --test

Tests use fixtures/fake-agy.mjs, which mimics agy's flags and output, so they need no Google account. PLAN.md documents the design, the measured agy behaviour and the module contracts.

Credits

Job supervision, quota, completion-wake hook and doctor ideas come from tphakala/agy-mcp (MIT). No code was copied.

Licence

MIT. See LICENSE.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables STDIO-compatible AI assistants to queue coding work onto the official Google Antigravity CLI and track status, read reports or patches, query capabilities, or cancel running tasks without blocking. Supports trusted direct execution plus optional isolated or read-only modes depending on the platform.
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Lets MCP clients such as Claude Code, Claude Desktop, Cursor, or Codex hand tasks to the Antigravity CLI (agy) so the work runs on the user's Antigravity plan instead of the client's. Exposes tools for delegated coding tasks and reviews, web search with sources, image/PDF analysis, shell command generation or execution, brainstorming, and model/quota checks.
      7
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Lets Claude Code and Claude Desktop delegate tasks to Google Antigravity on Windows, running headless CLI jobs with command approval, token tracking, and exported markdown results. Optionally runs tasks as real conversations inside the Antigravity desktop app so they can be watched and opened there.
      1
      MIT