# Agent Antigravity MCP Server

Model Context Protocol (MCP) server for Google Gemini Antigravity Agent.

## Features

- **Autonomous Code Execution**: Run shell, Python, Node.js commands in remote Linux sandbox.
- **Web Browsing & Search**: Integrated `google_search` and `url_context`.
- **Multimodal Inputs**: Process text instructions and base64 images.
- **Custom Functions**: Support turn-based custom function calling.
- **Remote MCP Servers**: Connect external MCP servers to Antigravity agent.
- **Model Selection**: Choose between `gemini-3.6-flash`, `gemini-3.5-flash-lite`, and other Gemini models.
- **Background Execution**: Async interactions with `background=True` polling and `max_total_tokens` budget cap.
- **Environment Config**: Build remote sandbox config with file sources (inline/git/gcs) and network allowlist.
- **Cron Triggers**: Create, list, pause/resume, delete, run, and audit scheduled recurring interactions.
- **GitHub PR Workflow**: Point at a repo (public/private) + base branch; agent branches, does the task, pushes, opens the PR. Token injected via sandbox network allowlist, never in the prompt.
- **Managed Agents**: Register reusable named agents (`system_instruction`, default tools, `base_environment`) and invoke them by ID.
- **Environments API**: List/inspect/delete sandbox environments directly, and download a sandbox's full filesystem as a `.tar`.
- **Hooks Config**: Mount a `hooks.json` (pre/post `code_execution`/file-op interception, allow/deny) into the sandbox via an inline environment source — format documented in `create_interaction`'s `environment` arg.

## Tools

| Tool | Covers |
| --- | --- |
| `create_interaction` / `continue_interaction` / `submit_function_result` | Interactions API create + multi-turn + function calling + `system_instruction` |
| `get_interaction_status` / `list_interactions` / `cancel_interaction` / `delete_interaction` | Interaction status, polling, cancel, delete |
| `create_trigger` / `list_triggers` / `get_trigger` / `update_trigger_status` / `delete_trigger` / `run_trigger` / `list_trigger_executions` | Triggers API (cron scheduling) |
| `create_github_pr_task` | Clone repo, branch, do task, push, open PR |
| `create_managed_agent` / `list_managed_agents` / `get_managed_agent` / `delete_managed_agent` | Managed Agents API (register + invoke by ID) |
| `create_environment` / `list_environments` / `get_environment` / `delete_environment` / `download_environment_files` / `upload_environment_file` | Environments API (sandbox lifecycle + file transfer) |

Note: the Interactions API supports `stream=true` for real-time step deltas via the
`google-genai` SDK directly (`AntigravityClient.create_interaction(..., stream=True)`),
but it's not exposed as an MCP tool — MCP tool calls are synchronous request/response,
so there's no way to surface incremental deltas over this transport.

## Installation

Clone it somewhere and note the full path:

```bash
git clone https://github.com/bgembalczyk/agent-antigravity-mcp.git
cd agent-antigravity-mcp && pwd
```

Every client below runs the server the same way — `uv run --project
<that path> agent-antigravity` over stdio — so you need
[uv](https://docs.astral.sh/uv/) installed, but no manual venv or `pip
install` step. In every snippet, replace `PATH_TO_REPO` with the `pwd`
output above (full path, not `~`).

### Claude Code (as a plugin, recommended)

No local clone needed — Claude Code clones it straight from GitHub:

```
/plugin marketplace add bgembalczyk/agent-antigravity-mcp
/plugin install agent-antigravity@agent-antigravity-mcp
```

Export `GEMINI_API_KEY`/`GITHUB_TOKEN` in your shell profile before launching
Claude Code — the plugin's `.mcp.json` reads them via `${GEMINI_API_KEY}`/`${GITHUB_TOKEN}`.

### Antigravity CLI / IDE

File: `~/.gemini/config/mcp_config.json`

```json
"agent-antigravity": {
  "command": "uv",
  "args": ["run", "--project", "PATH_TO_REPO", "agent-antigravity"],
  "env": { "GEMINI_API_KEY": "${GEMINI_API_KEY}", "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
}
```

Paste that inside the top-level `"mcpServers": { ... }` object (create it with
just `{"mcpServers": {}}` if the file doesn't exist yet).

### Codex CLI

File: `~/.codex/config.toml`

```toml
[mcp_servers.agent-antigravity]
command = "uv"
args = ["run", "--project", "PATH_TO_REPO", "agent-antigravity"]

[mcp_servers.agent-antigravity.env]
GEMINI_API_KEY = "your_gemini_api_key"
GITHUB_TOKEN = "your_github_pat_with_repo_scope"
```

Append that to the end of the file — TOML tables don't care what's above
them. Codex doesn't expand shell vars here, so put the real key values in.

### GitHub Copilot CLI

File: `~/.copilot/mcp-config.json`

```json
"agent-antigravity": {
  "type": "local",
  "command": "uv",
  "args": ["run", "--project", "PATH_TO_REPO", "agent-antigravity"],
  "env": { "GEMINI_API_KEY": "your_gemini_api_key", "GITHUB_TOKEN": "your_github_pat_with_repo_scope" },
  "tools": ["*"]
}
```

Paste inside `"mcpServers": { ... }` (create the file with `{"mcpServers": {}}`
if needed). Takes effect immediately, no restart. Same as Codex, real values
in `env` — Copilot CLI doesn't expand shell vars here either.

### OpenCode

File: `~/.config/opencode/.opencode.json` (global) or `opencode.json` in a
project root (project-scoped).

```json
"agent-antigravity": {
  "type": "local",
  "command": ["uv", "run", "--project", "PATH_TO_REPO", "agent-antigravity"],
  "environment": { "GEMINI_API_KEY": "{env:GEMINI_API_KEY}", "GITHUB_TOKEN": "{env:GITHUB_TOKEN}" }
}
```

Paste inside `"mcp": { ... }` (create with `{"mcp": {}}` if needed).
`{env:VAR_NAME}` expands from your shell environment at startup. Restart
OpenCode (or reload config) after saving.

### Any other MCP client / standalone

Any client that speaks MCP over stdio can launch this server the same way:
`uv run --project PATH_TO_REPO agent-antigravity`. If you'd rather manage the
virtualenv yourself instead of letting `uv run` do it:

```bash
uv venv --clear venv
uv pip install -e .
venv/bin/agent-antigravity
```

## Configuration

Create `.env` file:

```env
GEMINI_API_KEY=your_gemini_api_key
GITHUB_TOKEN=your_github_pat_with_repo_scope
```

`GITHUB_TOKEN` fallback used by `create_github_pr_task` when no `github_token` param given. Needs `repo` scope for private repos.

Optional:

```env
AGENT_ANTIGRAVITY_LOG_LEVEL=INFO
AGENT_ANTIGRAVITY_SESSIONS_DB=/custom/path/sessions.db
AGENT_ANTIGRAVITY_TRANSPORT=stdio        # stdio | sse | streamable-http
AGENT_ANTIGRAVITY_HOST=127.0.0.1         # sse/streamable-http only
AGENT_ANTIGRAVITY_PORT=8000              # sse/streamable-http only
AGENT_ANTIGRAVITY_MAX_REQUESTS_PER_MINUTE=60  # 0 disables limiting
```

## Usage

Once registered with any client above, the server starts automatically over
stdio whenever that client launches — nothing to run manually. In Claude Code,
the `agent-antigravity` skill (`skills/agent-antigravity/SKILL.md`) also
auto-activates when a task matches, on top of the raw MCP tools being available.

## Reliability

- Every API call tries the `google-genai` SDK first, falls back to direct REST on
  failure (logged at WARNING). REST calls retry on `429`/`5xx`/transport errors with
  exponential backoff (3 attempts).
- Interaction session cache is SQLite-backed (`~/.agent-antigravity/sessions.db` by
  default) and survives process restarts.
- CI (`.github/workflows/test.yml`) runs the test suite on every push/PR.

## Testing

```bash
uv pip install -e ".[dev]"
pytest -q
```

## Credit

Structure and tool/resource/prompt patterns inspired by [jules-mcp-server](https://github.com/savethepolarbears/jules-mcp-server), an MCP server for Google Jules.

## License

MIT — see [LICENSE](LICENSE).