antigravity-cli-mcp

An MCP (Model Context Protocol) server wrapping the agy (antigravity) CLI. This server exposes the capabilities of the agy tool to MCP clients like Claude Code, Codex, OpenCode, Cline, Kilocode, Kilo, and other stdio JSON-RPC compatible LLM interfaces.

Features

• Exposes 4 core tools: ping, ask-agy, search-web, and write-file.

• Manages subprocess execution using Bun's fast Bun.spawn engine.

• Implements concurrency limits and resource constraints (timeout, max memory/output bytes, workspace directory confinement).

• Emits real-time streaming progress notifications back to the LLM client using MCP notifications/progress protocol.

• Strict path validation to ensure file access does not escape the workspace.

Related MCP server: gemini-bridge

Verified Integrations

Installation & Registration

Prerequisites

• Bun (v1.0.0 or higher) installed.

• agy (antigravity CLI) binary installed on your system.

Installation

1. Install globally via npm/bun:

npm install -g antigravity-cli-mcp
# or
bun add -g antigravity-cli-mcp

2. Or use directly with npx/bunx without installing:

npx antigravity-cli-mcp
# or
bunx antigravity-cli-mcp

Registering with Claude Code

# Using npm (after global install or via npx)
claude mcp add antigravity-cli-mcp -- npx antigravity-cli-mcp

# Development mode (from source)
claude mcp add antigravity-cli-mcp -- bun /path/to/antigravity-cli-mcp/src/index.ts

Registering with Codex CLI

Option A: Project-scoped Config (Automatic)

Codex will automatically load the server if you start it from inside this project directory, thanks to the included .codex/config.toml file:

[mcp_servers.antigravity-cli-mcp]
command = "bun"
args = ["src/index.ts"]

Option B: Global CLI Registration

To register the server globally so it is available across all directories:

# Using npm (after global install or via npx)
codex mcp add antigravity-cli-mcp -- npx antigravity-cli-mcp

# Development mode (from source)
codex mcp add antigravity-cli-mcp -- bun /path/to/antigravity-cli-mcp/src/index.ts

Registering with Cline / Kilocode

Cline and Kilocode store MCP server config in a cline_mcp_settings.json file inside their VS Code extension's global storage directory.

Cline (saoudrizwan.claude-dev):

~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

Kilocode (kilocode.kilo-code):

~/Library/Application Support/Code/User/globalStorage/kilocode.kilo-code/settings/cline_mcp_settings.json

Add the following entry to the mcpServers object in the appropriate file:

Using npm (after global install or via npx):

{
  "mcpServers": {
    "antigravity-cli-mcp": {
      "command": "npx",
      "args": ["-y", "antigravity-cli-mcp"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

Development mode (from source):

{
  "mcpServers": {
    "antigravity-cli-mcp": {
      "command": "bun",
      "args": ["/path/to/antigravity-cli-mcp/src/index.ts"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

Replace /path/to/antigravity-cli-mcp with the absolute path to this repository. After saving, reload the VS Code window (Cmd+Shift+P → Developer: Reload Window) for the changes to take effect.

Registering with Kilo

Kilo is a standalone CLI tool installed at /opt/homebrew/bin/kilo (separate from the Kilocode VS Code extension).

To register the server with Kilo:

# Using npm (after global install or via npx)
kilo mcp add antigravity-cli-mcp -- npx antigravity-cli-mcp

# Development mode (from source)
kilo mcp add antigravity-cli-mcp -- bun /path/to/antigravity-cli-mcp/src/index.ts

Verification

Verify that the server has been added successfully:

kilo mcp list

Registering with OpenCode

Add to ~/.opencode/opencode.json (OpenCode reads global config from there):

Using npm (after global install or via npx):

{
  "mcp": {
    "antigravity-cli-mcp": {
      "type": "local",
      "command": ["npx", "-y", "antigravity-cli-mcp"]
    }
  }
}

Development mode (from source):

{
  "mcp": {
    "antigravity-cli-mcp": {
      "type": "local",
      "command": ["bun", "/path/to/antigravity-cli-mcp/src/index.ts"]
    }
  }
}

Verify with:

opencode mcp list
# antigravity-cli-mcp  connected

Configuration

You can configure the MCP server by setting the following environment variables:

Tools

The server registers 4 MCP tools:

1. ping

• Description: Check agy health, version, binary path, and active workspace root.

• Input Schema: {} (none)

• Response: Details of the agy binary version and execution capabilities.

2. ask-agy

• Description: Runs a prompt non-interactively with agy.

• Input Schema:

  • prompt (string, max 10k chars): The prompt to send to agy.

  • cwd (string, optional): Override the working directory.

  • timeout_ms (integer, optional): Override default execution timeout.

  • add_dirs (array of strings, optional): Extra directories to register for prompt context.

  • skip_permissions (boolean, optional): Skip safety/permission prompts by adding --dangerously-skip-permissions to the binary invocation.

3. search-web

• Description: Perform web search queries via agy. Results come from agy's search integration.

• Input Schema:

  • query (string, max 500 chars): The search query.

4. write-file

• Description: Write exact text content to a file inside the workspace root (does not call the agy binary).

• Input Schema:

  • path (string): The destination path (relative to the workspace root).

  • content (string, max 500k chars): The content to write.

  • create_parents (boolean, default false): If true, creates parent directories if they don't exist.

Streaming / Progress Notifications

For long-running CLI invocations, the ask-agy and search-web tools support progress updates. When an MCP client provides a progressToken in the tool call metadata:

1. The server listens to the raw stdout chunks from Bun.spawn().

2. It sends notifications/progress JSON-RPC updates containing the token, incremental sequence number, and the raw text output chunk as the message.

3. This allows compatible clients (such as Claude Code) to render output dynamically to the user while agy is still processing.

Development

All standard lifecycle scripts are managed through bun:

Running Tests

Execute the unit and integration test suite:

bun test

Type Checking

Validate the TypeScript codebase:

bun run typecheck

Building the Project

Compile the TypeScript code into a single executable bundle at dist/index.js:

bun run build

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Getting Started

1. Clone the repository:

   git clone git@github.com:nadimtuhin/antigravity-cli-mcp.git
   cd antigravity-cli-mcp

2. Install dependencies:

   bun install

Quality & Build Verification

Before submitting your PR, please verify your changes:

• Run tests:

  bun test

• Typecheck code:

  bun run typecheck

• Build the project:

  bun run build