Antigravity MCP

A lightweight Model Context Protocol (MCP) server that exposes the local Antigravity CLI (agy) to MCP-compatible coding agents.

The project intentionally keeps the architecture small: MCP tools validate inputs, a thin CLI adapter executes agy, and agy_raw provides an escape hatch for CLI options that are added in future Antigravity releases.

Features

• Run Antigravity as a local coding agent through MCP.

• Preserve conversation context with conversation IDs.

• Control common CLI options such as model, effort, sandbox, permissions, directories, timeouts, and output format.

• Inspect usage, quota, models, version, and help.

• Execute supported read-only slash commands.

• Pass arbitrary CLI arguments through agy_raw for forward compatibility.

• No shell execution: arguments are passed directly to the agy process.

Related MCP server: codex-agy-bridge

Requirements

• Node.js 18+

• Antigravity CLI installed and authenticated

• agy available on PATH

• An MCP-compatible client

If agy is not on PATH, set AGY_CMD to the executable path.

AGY_CMD=/custom/path/agy

Windows PowerShell:

$env:AGY_CMD = "C:\path\to\agy.exe"

Quick Start

The recommended setup is through npm. You do not need to clone this repository or install the MCP server manually.

Claude Code

claude mcp add --scope user antigravity -- npx -y antigravity-mcp

Verify the server:

claude mcp list

If agy is not on PATH:

claude mcp add --scope user \
  --env AGY_CMD=/custom/path/agy \
  antigravity -- npx -y antigravity-mcp

Windows PowerShell:

claude mcp add --scope user `
  --env AGY_CMD="C:\path\to\agy.exe" `
  antigravity -- npx -y antigravity-mcp

Gemini CLI

Gemini CLI supports adding local stdio MCP servers with gemini mcp add.

gemini mcp add --scope user antigravity npx -y antigravity-mcp

Verify:

gemini mcp list

Reference: Gemini CLI MCP documentation

Cursor

Add the following MCP server to Cursor's MCP configuration:

{
  "mcpServers": {
    "antigravity": {
      "command": "npx",
      "args": ["-y", "antigravity-mcp"]
    }
  }
}

Windsurf

Add the following stdio server to Windsurf's MCP configuration:

{
  "mcpServers": {
    "antigravity": {
      "command": "npx",
      "args": ["-y", "antigravity-mcp"]
    }
  }
}

Cline / Roo Code / Other MCP Clients

For MCP clients that expose a generic stdio configuration, use:

{
  "command": "npx",
  "args": ["-y", "antigravity-mcp"]
}

If the client supports environment variables, AGY_CMD can be set there as well.

Why npx?

npx lets MCP clients start the published package without requiring a local repository checkout. The client only needs Node.js and the Antigravity CLI.

To pin a specific version:

npx -y antigravity-mcp@1.0.1

Using npx -y antigravity-mcp follows the package version selected by npm's normal package resolution behavior.

Local Development

git clone https://github.com/alvarosw/antigravity-mcp.git
cd antigravity-mcp
npm install
npm start

No build step is required.

Tools

agy_run

Run Antigravity as an agent with common CLI controls:

• prompt

• model

• reasoning effort

• sandbox

• permission bypass

• additional directories

• conversation ID

• latest-conversation continuation

• print timeout

• output format

• additional raw arguments

• working directory

• environment variables

Example:

{
  "prompt": "Review the authentication implementation and identify security issues.",
  "cwd": "/workspace/project",
  "model": "gemini-3-flash",
  "effort": "high",
  "addDirs": ["/workspace/shared"],
  "sandbox": true
}

agy_usage

Runs Antigravity's /usage command in print mode.

agy_quota

Runs Antigravity's /quota command in print mode.

agy_models

Lists models available through the installed Antigravity CLI.

agy_version

Returns the installed CLI version.

agy_help

Shows CLI help. A command can be provided for command-specific help.

agy_readonly_command

Runs a read-only slash command through print mode. Examples include:

/usage
/quota
/model
/effort
/skills
/credits

The tool does not maintain a fixed command list, so newer read-only commands can be used as long as the installed CLI supports them.

agy_raw

Runs agy with an arbitrary argument array. This is the compatibility escape hatch for flags or commands not covered by the convenience tools.

Example:

{
  "args": ["models"]
}

Architecture

src/
├── index.js           # MCP server and tool registration
├── tools.js           # Tool behavior and response formatting
└── antigravity.js     # Thin process adapter for the agy CLI

Dependency direction:

MCP transport
    ↓
tool handlers
    ↓
agy CLI adapter
    ↓
local agy executable

There is intentionally no service container, repository layer, or framework abstraction. The project has one external process boundary and keeps that boundary explicit.

Security Notes

agy_raw can execute arbitrary Antigravity CLI arguments with the permissions of the user running the MCP server. The server itself does not invoke a shell, so tool arguments are not shell-interpreted, but agy still has whatever permissions the user grants it.

Use permission bypass options only when you explicitly trust the task and workspace.

Environment variables passed through the env field are inherited by the agy process. Avoid sending secrets through MCP tool arguments unless necessary.

License

MIT