mcp-server-google-antigravity

   ____ _                 _
  / ___| | __ _ _   _  __| | ___
 | |   | |/ _` | | | |/ _` |/ _ \
 | |___| | (_| | |_| | (_| |  __/
  \____|_|\__,_|\__,_|\__,_|\___|

               |
          +----+----+
          |   MCP   | (- you are here
          +----+----+
               |

     _          _   _                       _ _
    / \   _ __ | |_(_) __ _ _ __ __ ___   _(_) |_ _   _
   / _ \ | '_ \| __| |/ _` | '__/ _` \ \ / / | __| | | |
  / ___ \| | | | |_| | (_| | | | (_| |\ V /| | |_| |_| |
 /_/   \_\_| |_|\__|_|\__, |_|  \__,_| \_/ |_|\__|\__, |
                      |___/                       |___/

这是什么？

mcp-server-google-antigravity 是一个小型 MCP（模型上下文协议）服务。它将 Google Antigravity（由 agy CLI 驱动的 Google 终端编码 Agent，底层使用 Gemini）作为一组工具开放，供任何 MCP 客户端调用。

其理念是：你的主模型（Claude Desktop、Claude Code、Codex 等）保持精简，将繁重工作——网页搜索、整个代码库分析、搭建文件、长时间运行的编辑任务——委托给在后台运行的第二个 Agent。任务异步且不限量：提交任务后立即获取 jobId，然后轮询结果，同时调用方可以继续工作。

   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

要求

步骤 1 — 安装 Antigravity CLI（agy）

从未使用过 agy？从这里开始，只需运行一条命令。首次启动时会使用 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

安装位置（请记住此路径——稍后可能需要用于设置 AGY_PATH）：

登录并验证：

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, ...)

如果之后找不到 agy，请打开新的终端（以重新加载 PATH），或运行 agy install 修复 Shell 路径。

步骤 2 — 获取此 MCP 服务

**选项 A — npx（推荐）：**直接跳到步骤 3 并使用 npx 配置。npx 方式可直接通过公共 npm 注册表使用，无需身份验证。

或者，你也可以全局安装此软件包：

npm install -g mcp-server-google-antigravity

这会提供 mcp-server-google-antigravity 命令（你可以直接在 MCP 客户端的配置中注册该命令，而不是使用 npx）。

选项 B — 从源码安装（用于开发）：

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（仅用于在 Windows 上获得干净的输出）是一个可选依赖项——如果它无法在 macOS/Linux 上构建，安装仍会成功，服务会自动回退。无需编译器。

步骤 3 — 在 MCP 客户端中注册

{
  "mcpServers": {
    "antigravity": {
      "command": "npx",
      "args": ["-y", "mcp-server-google-antigravity"],
      "env": {
        "AGY_MODEL": "Gemini 3.5 Flash (Medium)",
        "AGY_AUTO_APPROVE": "true"
      },
      "timeout": 900000
    }
  }
}

# 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

就是这样。现在，客户端已拥有 use_antigravity、antigravity_continue 和文件系统辅助工具等工具。

快速示例

向 MCP 客户端提出类似 “使用 antigravity 分析 C:/Dev/Repos/foo 中的仓库，并总结其架构” 的请求。在底层，客户端会调用：

1. use_antigravity({ prompt: "...", add_dirs: ["C:/Dev/Repos/foo"] }) → 立即返回 { "jobId": "mrib1q20_wa5ma1", "status": "running" }。
2. antigravity_result({ jobId, wait_ms: 10000 }) → 阻塞/长轮询，直到任务完成或 10 秒等待时间结束。任务仍在运行时，会返回精简的负载，其中包含状态、字符数和输出的最后 200 个字符（{ status, jobId, chars, tail, startedAt }）。任务完成后，则返回完整记录（包括 durationMs 和 bytes 遥测数据）。

在同一会话中继续提问：antigravity_continue({ prompt: "now list the top 3 risks" })。需要 agy 写入文件？传入 add_dirs，为其指定工作区；auto_approve（默认值）允许其无需提示即可创建/编辑文件。

配置（环境变量）

所有配置项均为可选——开箱即用，且默认值合理。

工具

服务端文件系统工具直接使用 Node 的 fs，操作即时完成，且不会受权限提示限制。

实时进度通知

由于任务会立即返回 jobId，服务会推送 MCP 日志通知（notifications/message，日志记录器 antigravity），以便客户端无需轮询也能查看活动：

• job started — jobId、类型、提示词摘要
• job running — 每隔 AGY_HEARTBEAT_MS（默认 15s）发送一次心跳，并附上当前部分输出的尾部内容
• job done / job failed — 最终状态、字节数 / 错误

尽力而为：如果客户端未协商 logging 功能，通知会被静默丢弃。无论如何，轮询 antigravity_result 都能正常工作。

工作原理（设计说明）

agy CLI 使用 agy --print "<prompt>" 运行单条提示词，并在完成后返回。这里有三个问题及其解决方法：

1. MCP 客户端请求超时（约 60s）。 长任务会导致客户端放弃请求，即使 agy 仍在运行。→ 异步任务模式： use_antigravity 在后台启动 agy，立即返回 jobId，将结果写入 OS 临时目录（agy_jobs/）中的 JSON 文件，由客户端轮询 antigravity_result。可选的长轮询（wait_ms）允许客户端在预期运行时间较短时等待请求完成。请求不会被阻塞。
2. agy 自身的打印超时（默认 5m）。 复杂提示词会导致 timeout waiting for response。→ 每个任务都会传入 --print-timeout 10m。
3. 无头模式下的文件权限门控。 在 --print 模式下，agy 的文件写入会被 "ask" 策略拒绝，导致任务挂起。→ auto_approve（默认 true）会传入 --dangerously-skip-permissions；add_dirs 会为所需工作区传入 --add-dir <path>。

安全说明

auto_approve 默认为 true（--dangerously-skip-permissions）——agy 会创建/编辑文件并运行终端命令，而不会提示确认。这是有意为之：在无头 --print 模式下，agy 否则会卡在权限提示上，导致任务挂起。对于不受信任的提示词，建议使用 sandbox: true（限制终端，开销低——它是权限层，不是 VM），而不是关闭自动批准。仅在确实只读的请求中使用 auto_approve: false。

平台支持

完全跨平台——macOS、Windows 和 Linux。Windows 使用 node-pty 路径实现流畅的流式传输（如果不可用，则自动回退），并自动解析非 ASCII 用户名的 8.3 短路径；macOS/Linux 使用普通的 child_process。各操作系统之间唯一的区别是 agy 所在的位置和客户端的配置文件所在的位置（以上均已说明）。

故障排除

许可证

MIT © Türker Yakup Altınsoy.