google-flow-mcp

An MCP server that lets AI agents like Claude generate images in Google Flow and download them to disk.

An agent can:

• choose the model, aspect ratio and number of images

• submit a prompt and wait for the results

• download them at 1K (original), 2K or 4K (upscaled)

It works by operating the real Flow web app in a Chrome window that you sign into once. You don't need an API key.

Unofficial. This project is not affiliated with or endorsed by Google. It automates Flow's web UI on your own account, using your own subscription and credits. Review Google's terms before using it heavily, and expect breakage when Flow changes its UI.

Contents

• Requirements

• Install

• First run

• Tools

• Configuration

• How it works

• Troubleshooting

• Security

• Contributing

Related MCP server: google-flow-mcp

Requirements

• Node.js 20 or newer

• Google Chrome (or Chromium)

• A Google account with access to Flow (a Google AI plan for paid models and credits)

Install

git clone https://github.com/Dilantha-Wijesinghe/google-flow-mcp.git
cd google-flow-mcp
npm install        # also builds dist/

Claude Code

claude mcp add google-flow -- node /absolute/path/to/google-flow-mcp/dist/index.js

Claude Desktop and other MCP clients

{
  "mcpServers": {
    "google-flow": {
      "command": "node",
      "args": ["/absolute/path/to/google-flow-mcp/dist/index.js"]
    }
  }
}

First run

1. Ask your agent to call flow_status, or run npm run call -- flow_status.

2. The server launches Chrome with a dedicated profile (~/.flow-mcp/chrome-profile) and remote debugging on 127.0.0.1:9222.

3. Sign into Google in that window and open flow.google.com once. The sign-in persists for later sessions.

Why a separate profile? Chrome 136 and later refuse remote debugging on your everyday profile. Google sign-in also blocks browsers launched by automation tools. So the server starts a normal Chrome process on its own profile and attaches to it.

Tools

flow_generate_images arguments

Example

"Generate 4 cinematic 16:9 images of a lighthouse at golden hour with Nano Banana Pro and save them to ~/Pictures/lighthouse."

The agent calls:

{
  "prompt": "A lighthouse on a rocky coast at golden hour, cinematic wide shot",
  "model": "Nano Banana Pro",
  "aspect_ratio": "16:9",
  "count": 4,
  "download_size": "1K",
  "output_dir": "/Users/you/Pictures/lighthouse"
}

And it gets back:

{
  "projectUrl": "https://flow.google.com/project/…",
  "mediaIds": ["37be9df5-…", "38d1a484-…", "…"],
  "credits": 0,
  "settings": "Nano Banana Pro · 16:9 · x4",
  "files": [{ "mediaId": "37be9df5-…", "path": "/Users/you/Pictures/lighthouse/Lighthouse_…_1K_37be9df5.jpg", "bytes": 917811 }],
  "failures": []
}

Command-line testing

npm run call                                  # list tools
npm run call -- flow_status
npm run call -- flow_get_options
npm run call -- flow_generate_images '{"prompt":"a red fox in snow","aspect_ratio":"16:9","count":2,"download_size":"1K"}'

Configuration

Set these environment variables in your MCP client config:

How it works

These details were observed on flow.google.com in October 2026.

• Settings: the prompt bar's settings chip opens a popover containing:

  • Image/Video toggles, aspect ratio and count, all Angular Material role=radio buttons matched by label.

  • A model menu.

• Prompt: a ProseMirror editor. The server types into it with real keyboard input.

• Credits: before submitting, the server reads the "Generating will use N credits" line and enforces max_credits.

• Progress: each pending image shows a .loading-percentage placeholder. Finished images are <img data-media-id> tiles. New images are found by diffing media ids before and after.

• Download: the tile menu offers Download → 1K, 2K or 4K. Flow builds the file as a blob: URL and clicks an <a download>. The server intercepts only the click it triggered and writes the bytes where you asked, so Chrome's download settings don't matter.

• One job at a time: jobs are serialized. Flow attaches a single-use reCAPTCHA token to each generation and flags rapid-fire requests.

All selectors live in SEL at the top of src/flow.ts.

Why UI automation and not Flow's private API?

In September 2026 Flow moved from labs.google/fx to flow.google.com, and the old aisandbox-pa.googleapis.com endpoints stopped working. The new backend uses Google's internal batchexecute RPC, and each generation needs a single-use reCAPTCHA Enterprise token minted in the browser. Replaying that traffic over plain HTTP means working around the bot check. It also breaks every time RPC ids rotate. Driving the real UI is slower, around 20 seconds per batch, but it stays within normal use of the site.

Troubleshooting

Known limitations

• Images only. Flow's video mode is not wired up yet.

• 2K and 4K downloads trigger Flow's upscaler, which may use credits. max_credits does not cover upscaling.

• Tested on macOS with Chrome 155. Windows and Linux paths are auto-detected but less tested.

Security

• ~/.flow-mcp/chrome-profile holds a signed-in Google session. Treat it like a password and never share or commit it.

• The DevTools port is bound to 127.0.0.1. Anything running locally as your user can drive that browser while it is open, so close the window when you're not using it.

• To report a vulnerability, use GitHub's private vulnerability reporting.

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md.

Related projects

These were reviewed while building this one:

• miyakejima/google-flow-mcp

• luongvietan/google-flow-mcp

• TMSSS05/google-flow-browser-mcp

• Mitanshp5/Google-Flow_MCP

• crisng95/flowkit

License

MIT