<div align="center">

Google Flow MCP

Generate and download Google Flow videos and images directly from AI agents—using your existing Google subscription, with no generation API key.

Works with OpenAI Codex, Google Antigravity, and other local stdio MCP clients.

Features · Install · Connect an account · Clients · Tools · Security

</div>

---

Google Flow MCP is a local Model Context Protocol server that lets an AI agent operate Google Flow through a user-owned Chromium session. It can discover the exact options available to each account, generate media with Flow subscription credits, wait for long-running jobs, use the upscale choices Flow actually offers, and save validated files directly into a project.

It does not require a Google generation API key. Credits are consumed through the Flow website just as they are when the user operates Flow manually.

Installing with an agent? Tell it to read AGENTS.md and follow INSTALL.md. The supported Antigravity command is npm run setup:antigravity. Installer agents must not modify source, install Playwright Chromium, generate tool schemas, or use an Antigravity scratch directory.

Why Google Flow MCP

The agent knows what the account can actually do

flow_inspect_account returns a live, normalized capability contract instead of relying on hardcoded assumptions:

• Image and video models, with stable IDs and the currently selected model
• Aspect ratios separated by media type
• Output counts separated by media type
• Selectable durations—only when Flow exposes a duration control
• Preview, original, available upscale, and unavailable/upgrade-only asset options
• Current Flow UI language and login state

Example from a real Spanish-language Flow account:

{
  "models": {
    "image": [
      { "id": "nano-banana-pro", "label": "Nano Banana Pro", "selected": false },
      { "id": "nano-banana-2", "label": "Nano Banana 2", "selected": true },
      { "id": "nano-banana-2-lite", "label": "Nano Banana 2 Lite", "selected": false }
    ],
    "video": [
      { "id": "omni-flash", "label": "Omni Flash", "selected": true },
      { "id": "veo-3-1-lite", "label": "Veo 3.1 - Lite", "selected": false },
      { "id": "veo-3-1-fast", "label": "Veo 3.1 - Fast", "selected": false },
      { "id": "veo-3-1-quality", "label": "Veo 3.1 - Quality", "selected": false }
    ]
  },
  "aspectRatiosByMedia": {
    "image": ["16:9", "4:3", "1:1", "3:4", "9:16"],
    "video": ["16:9", "9:16"]
  },
  "outputCountsByMedia": {
    "image": [1, 2, 3, 4],
    "video": [1, 2, 3, 4]
  },
  "visibleDurations": [],
  "availableUpscales": ["1080p"],
  "unavailableUpscales": ["4k"]
}

If Flow does not offer a requested model, ratio, duration, output count, or upscale, the MCP fails explicitly. It never silently substitutes a different paid option.

Account connection without entering credentials again

The bundled Flow Login Bridge extension reuses Google accounts already signed into the user's normal Chromium profile. Connection is deliberately split into two MCP calls so the agent can explain each user action instead of disappearing into a long-running tool:

1. flow_begin_account_connection returns immediately and instructs the agent to stop and tell the user what to click.
2. The user clicks Connect Flow in the extension and replies connected after it says Session sent.
3. flow_complete_account_connection opens Google's existing-account chooser; the user clicks the desired account.
4. The actual Flow workspace is verified, the temporary window closes, and future automation uses an isolated persistent session.

No email entry, password entry, 2FA entry, cookie JSON, Chromium restart, or remote-debugging launch is required for the normal login path.

End-to-end media delivery

• Generates video with Omni Flash or the Veo models exposed by the account
• Generates or edits images with the Nano Banana models exposed by the account
• Accepts prompts in any language
• Supports ratios, output counts, optional references, and durations when available
• Persists jobs that outlive an MCP request timeout
• Detects Flow's real asset-menu upscale choices, including resolution-based options such as 1080p
• Captures browser downloads into an absolute project directory
• Correlates every download to the exact asset identities created by that job, independent of gallery order
• Downloads originals from the tracked Flow media URL, without relying on a visible gallery card or translated context menu
• Fails closed instead of guessing when Flow cannot expose a unique job-to-asset match
• Writes a .flow.json reproducibility manifest
• Records SHA-256 and file size for every download
• Adds duration, dimensions, codec, and format when ffprobe is installed
• Saves diagnostic screenshots when Flow's UI changes

Designed for agents without hiding credit use

Generation and upscale tools require confirmCreditSpend: true. The agent should set it only after the user explicitly asks for a credit-consuming operation. Read-only inspection, status, and account-list tools do not spend credits.

Flow MCP also owns Flow's separate in-browser confirmation preference. Before submitting a generation, it opens the isolated managed profile's Agent settings, selects the language-independent AUTO_APPROVE value (shown as Never / Nunca), saves it, reopens the settings, and verifies that it persisted. If Flow still displays an approval card, the MCP selects the final persistent approval action—Approve and don't ask again—instead of leaving the agent waiting or choosing the one-time approval.

This does not bypass the MCP credit guard: a generation or upscale still runs only when the user requested it and the tool call includes confirmCreditSpend: true.

Prevents browser-tool detours

The MCP publishes a server-level execution contract as part of the MCP initialization handshake and repeats the critical rules in every relevant tool description and response:

• Flow generation must use flow_generate_video or flow_generate_image
• Generic browser, computer-use, keyboard, mouse, and web tools must never operate the Flow website
• A generation has started only when a generation tool returns a persistent job ID
• A Google account avatar is not treated as proof that the Flow workspace is available
• The public Flow landing page is classified separately and causes an immediate flow_access_unavailable error
• Only a workspace-verified account can become the default or spend credits

This prevents an agent from scrolling around Flow's marketing site when the selected Google account is signed in but does not expose the generation workspace.

Quick start

Requirements

• Node.js 20 or newer
• Chromium or Google Chrome
• A Google account with access to Flow in a supported region
• Optional: ffprobe on PATH for richer media validation

Install

git clone https://github.com/retrolyze52/google-flow-mcp.git
cd google-flow-mcp
npm ci
npm run check

Playwright controls the locally installed Chromium/Chrome executable; it does not require a separate bundled browser download. Do not run npx playwright install chromium. Set FLOW_MCP_BROWSER_EXECUTABLE to an absolute browser path only if auto-detection cannot find a normal system browser. See the complete installation guide.

Connect your Google account

1. Install the Flow Login Bridge once

The reviewed extension source is included in extension/. It reads Google cookies only after the user clicks Connect Flow and sends them only to the MCP bridge bound to 127.0.0.1. It never reads passwords or 2FA codes.

On Windows with Chromium:

npm run install-extension

The helper copies the extension path and opens chrome://extensions/. Then:

1. Enable Developer mode.
2. Click Load unpacked.
3. Select the repository's extension directory.

For Chrome or another desktop platform, open chrome://extensions/ manually and follow the same three steps. No browser restart is needed.

2. Start connection from the agent

Ask the agent:

Connect my Google Flow account as personal.

The correct interaction is:

1. The agent calls flow_begin_account_connection, shows you its instructions, and stops.
2. Open Flow Login Bridge in the already-running normal browser and click Connect Flow.
3. When the popup says Session sent, return to the agent and reply connected.
4. The agent tells you a temporary chooser will open and calls flow_complete_account_connection.
5. Click one of the existing Google accounts shown in the temporary chooser.

That is the complete normal login flow. Completion is detected automatically and the temporary Flow window closes.

To connect additional accounts, repeat the process with IDs such as studio or backup. Each account receives an isolated persistent browser profile. Operations for one account are serialized; separate accounts can progress independently.

CLI equivalents are also available:

npm run account -- connect personal "Personal Google Pro"
npm run account -- connect studio "Studio account"
npm run account -- list

Advanced: attach to localhost CDP

If a browser was deliberately started with a localhost remote-debugging port, the MCP can attach without copying cookies:

npm run account -- connect personal "Main Chromium" --cdp http://127.0.0.1:9222

Only localhost CDP endpoints are accepted, and attached browsers are never closed by the MCP. The extension flow is recommended for normal setup.

Connect your MCP client

Run npm run build first. Replace the paths below with the absolute location of dist/index.js.

OpenAI Codex

Add this to ~/.codex/config.toml:

[mcp_servers.google_flow]
command = "node"
args = ["C:\\absolute\\path\\to\\google-flow-mcp\\dist\\index.js"]
enabled = true
startup_timeout_sec = 30
tool_timeout_sec = 1200

[mcp_servers.google_flow.env]
FLOW_MCP_HEADLESS = "0"

Open a new Codex task after changing MCP configuration. This does not restart Chromium or require another Google login.

Google Antigravity

Antigravity 2.0, Antigravity IDE, and Antigravity CLI support local stdio MCP servers. Clone into a stable directory—not Antigravity's disposable scratch directory—then run the supported installer:

git clone https://github.com/retrolyze52/google-flow-mcp.git "$env:LOCALAPPDATA\google-flow-mcp"
Set-Location "$env:LOCALAPPDATA\google-flow-mcp"
npm run setup:antigravity

The installer enforces a clean source tree, runs all checks, detects a normal browser, preserves unrelated MCP servers, backs up the existing config, and writes the official ~/.gemini/config/mcp_config.json stdio structure with absolute command, args, and cwd paths. Then open Settings → Customizations → Installed MCP Servers and click Refresh. Antigravity discovers schemas automatically; do not generate them. This refresh does not restart Chromium or lose connected Flow accounts. See INSTALL.md and Google's official Antigravity MCP documentation.

Other stdio MCP clients

{
  "mcpServers": {
    "google-flow": {
      "command": "node",
      "