google-flow-mcp

Drive Google Flow (Veo video, Nano Banana images) from a terminal and from an AI agent: read projects, media and credits; create and delete projects, characters and scenes; upload media; generate images and video; assemble scenes into a film. Every paid action is written to a ledger before the click, and an MCP server exposes the whole surface to Claude Code or any MCP client.

Everything in this README was measured on a real account, not inferred from the code. Where a number has not been measured, it says so.

This is not an official Google project. It automates the Flow web app through a real browser session. Read Risk before you run anything.

What it is, and what it is not

It is a control layer: 43 MCP tools plus a CLI, with a spend ledger, a double-charge guard, and prices in every tool description.

It is not a video maker. The script, the shot list, the camera angles and the quality of the result are the job of the agent using these tools. The repo owner settled this on 2026-09-13; the story package is only a worked example and a place to exercise the paid paths for real.

Related MCP server: Google Flow Browser MCP

Will it run for you?

All four must be true. The first one is the one that catches people.

A Google AI Pro (or higher) plan is what the measured prices below come from. Flow tops the balance up by about 50 credits a day on that plan, which is why a balance can go up between two readings: never infer spending from the difference between two readings taken far apart.

Install

git clone https://github.com/hainguyen-keyti/google-flow-mcp.git
cd google-flow-mcp
uv sync --group dev
uv run video --help

Check the lane before anything else. This costs nothing and tells you whether the account is usable:

uv run video flow lane

verdict: MIGRATED means you are on the supported lane. Anything else means the tools here will not work for that account, and no amount of retrying will change it.

Quickstart

Free reads:

uv run video flow projects
uv run video flow credits
uv run video flow media <project_id>

A paid generation, 10 credits on the measured plan, written to out/ledger.jsonl:

uv run video gen t2v "a red paper boat drifting on a pond" --project <project_id> --model veo-lite --out out

Using it from an agent (MCP)

cp .mcp.json.example .mcp.json

Edit the copy if uv is not on your PATH, then open the folder with an MCP client (Claude Code reads .mcp.json from the project root). The server serves 43 tools; every description carries its price.

A server that is already running does not pick up new code, and an open session keeps the old tool descriptions: after changing anything here, start a new session.

See docs/tools.md for the full tool list with prices, generated from the running server rather than typed by hand.

What a call costs

Measured on a Google AI Pro account in September 2026. A price marked unmeasured is one this repo refuses to guess about; the tool says so too.

Timing, so a slow call is not mistaken for a broken one: a read takes 15 to 50 s, a change about 50 s, a generation 2 to 5 min, clip_extend and clip_edit up to 7 min.

How the money is guarded

These are not suggestions; they are enforced in code and pinned by tests.

• A ledger line is written before the click, not after. A driver that dies mid-action leaves a submitted row, never a silent charge. This exists because 20 credits were once spent with an empty ledger.

• A job_id is spent once. Before opening a browser, a paid tool refuses any job_id that appears in ANY ledger.jsonl under out/, and refuses one that another call is running right now. Retrying with the same id is safe; inventing a new id for a job you already paid for is how you buy the same thing twice.

• Outputs stay inside out/. Every tool that writes a file or a ledger forces its target inside out/.

• Click once, then wait. Flow submits late, about 20 s after the click. Leaving the page early cancels the request in flight and looks exactly like a dead button; clicking again submits a second, paid job.

• Prices live in the tool description, and a tool refuses a cell whose price nobody has measured.

Risk, read this before the first run

• This drives the Flow web app with your logged-in browser profile. That may be against Google's terms for your account; you are the one taking that risk. If Flow flags unusual activity (a WAF rejection), the tools stop and tell you: do not retry and do not re-authenticate.

• Generations spend real credits. Nothing here asks for confirmation on your behalf; if you wire these tools into an autonomous agent, you are wiring it to your wallet.

• Generated clips carry Google's visible sparkle watermark. Removing it is your decision and your jurisdiction's problem, not something this repo does for you.

Known limits

• macOS only, one account lane (flow.google.com), one browser (real Chrome with the gflow profile).

• clip_edit does not read the live price line before clicking, unlike gen_character: the only guard is the balance read before and after.

• Trimming a clip's head or tail inside a scene is not implemented.

• Deliberately out of scope: collections, media rename, media trash, project zip export, the Tools gallery, Flow's own agent mode beyond an on/off switch, Omni 360p and upscale, project settings, GIF export, share links and publishing to YouTube.

Testing

uv run ruff check . && uv run ruff format --check . && uv run pytest

893 tests, none of which call Flow or spend anything: tests use fixtures and fakes, which is a hard rule here. About 25 of them do render and measure real video, so ffmpeg must be installed, and two of them draw captions, so a unicode font must exist: macOS ships one, on Linux install fonts-dejavu-core or point VIDEO_FONT at a .ttf or .ttc of your own. The live acceptance scripts under scripts/acceptance/ do talk to Flow, are read-only by default, and say in their own output what they spent.

Documentation

License

MIT, see LICENSE.