flow-mcp

Drive Google Flow (flow.google.com) from Claude, Codex or any other MCP app, or from a local control
panel, using Flow's own credits (free with any Google account: 50 a day), not the pay-per-use video API.

It is a small program that runs on your own machine. It opens its own Chrome window, signs in
as you, and clicks Flow's real buttons. There is no browser extension, no hosted service and no
account to create.

Claude / Codex ──stdio──> flow-mcp ──Chrome DevTools Protocol──> Chrome (its own profile) ──> Flow

MCP = Model Context Protocol, the standard that lets Claude use outside tools.
New here? GETTING-STARTED.md takes you from nothing to your first video, step by step, and
OVERVIEW.md explains what it does in plain English, with no code names.

What you need

A display must stay awake: the Chrome window is really being driven, so the machine cannot be
headless or asleep mid-run.

Install

git clone https://github.com/GTAI-1/flow-mcp.git
cd flow-mcp
npm install
npm run build

Mac: do not put this folder in ~/Desktop, ~/Documents or ~/Downloads. macOS protects those
folders, and apps that launch the server from there can be refused permission to read its own
files (EPERM: operation not permitted). ~/flow-mcp or anywhere in your home folder is fine.

Windows: keep it out of folders OneDrive syncs (often Desktop and Documents), where files can be held
online-only. C:\Users\<you>\flow-mcp is fine.

Then sign in, once:

npm run login

That opens the dedicated Chrome window. Sign into Google by hand, open (or create) a Flow project,
and leave the window open. The program never types your password; it only uses the session you
created. That Chrome profile lives in ~/.flow-mcp/chrome-profile and is separate from your
everyday browser.

Connect it to Claude, Codex or Antigravity

Claude Code

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

--scope user makes it available in every folder; the default (local) only works in the folder you ran it from.

Claude Desktop: add to claude_desktop_config.json (Mac: ~/Library/Application Support/Claude/, Windows:
%APPDATA%\Claude\). On Windows, write the path with doubled backslashes, like
"C:\\Users\\you\\flow-mcp\\dist\\index.js":

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

Codex: add to ~/.codex/config.toml (on Windows, %USERPROFILE%\.codex\config.toml):

[mcp_servers.flow]
command = "node"
args = ["/absolute/path/to/flow-mcp/dist/index.js"]

Or run codex mcp add flow -- node /absolute/path/to/flow-mcp/dist/index.js. No timeout setting is needed:
Codex, like most MCP apps, gives up on a tool call after 60 seconds, so any call that runs longer than about
45 seconds (creating a character, a 1080p download) answers with a task id instead and keeps working, and
flow_wait collects the result.

Antigravity (Google's coding app): add a flow entry to mcp_config.json. On a Mac it lives in
~/.gemini/antigravity/; you can also open it from the agent panel's … menu → Manage MCP Servers →
View raw config. Keep any servers already listed and add this one beside them:

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

Other MCP apps (Cursor, VS Code and others) take the same command and arguments in their own MCP
settings. ChatGPT in the browser or the ChatGPT app can't use it: its connectors only reach servers on
the internet, and this tool has to run on your own computer to drive your Chrome window.

Developed and tested with Claude. Codex and Antigravity speak the same protocol, so they should work the
same way, but neither has been tried yet, so please report how it goes. Running two of them at once is safe:
the first one started drives Flow, and the others pass their requests to it.

Restart the app, then ask it: "check my Flow session". You should get your plan and credit balance
back. Everything after that is plain English; you never type tool names.

Your first film

Nothing below costs a credit until step 4, and the assistant asks before spending.

1. Check the session. "Check my Flow session." This confirms sign-in, plan and credits.
2. Make a character. "Create a character called Pip, a small lamplighter in a flat cartoon style."
   Flow draws the portrait. Free.
3. Draw the key frames. "Draw three stills with Pip: a dark rooftop, him lighting a lamp, the
   whole hillside glowing. Match each one to the last." Free: stills cost nothing, so get the look
   right here before spending.
4. Shoot it. "Turn those into three 10-second shots, each starting where the last one ended,
   720p, no more than 15 credits each." This spends credits. The price is read from Flow's own
   quote first and the scene is skipped if it is over your cap.
5. Narrate it. "Record this line with a warm documentary voice." Free, any length.
6. Cut it. "Join the three shots under the narration, don't freeze the last frame."
   The finished file lands in ~/flow-mcp-out/<project>/.

The control panel

The same features, without an AI assistant in the loop:

npm run studio     # then open http://127.0.0.1:8787

or double-click Flow Studio.command (Mac) or Flow Studio.cmd (Windows).

Seven tabs, in the order you would use them:

• Cast: reusable characters. Create them, edit them in place, or build one from a picture.
• Frames: free stills, with match previous frame to keep a set on-model.
• Shots: paid clips, with first/last frames, chaining, a live credit estimate, and a card that
  continues a finished clip from its own last frame.
• Voice: free narration in Google's voices or your computer's own. Your saved narrations are listed
  here to play or delete, and there's a field for your Google AI Studio key (checked with Google, stored
  only on your computer; never paste it into a chat).
• Restyle: change a clip you already have.
• Cut: join any videos into one film, in the order you pick. Upload one, or choose from films you've
  already made. Add a narration (from your saved ones or an upload) and music, and turn the clips' own
  sound down so the narration sits on top.
• Library: everything in your Flow project. Download it again for free (a scene comes down as one
  finished film, not loose clips), or move it to Flow's Trash.

A progress monitor and a gallery of your saved work sit alongside. The gallery shows stills or clips
on the tabs that use them. On a wide screen, each side scrolls on its own. Two kinds of delete, clearly
labelled: Move to the Mac's Trash / Recycle Bin removes a file from your computer; Move to
Flow's Trash removes it from your Flow project only. Both can be undone.

The panel ships with the repo but is not started for you: run npm run studio when you want it.
Opening studio/index.html as a plain file does nothing; the page needs the server behind it, and
says so in red if you try.

Claude's own process serves the same panel while it runs. Whichever process starts first owns the
Chrome tab and the job queue; the other talks to it over a local API, so Claude and the panel always
agree on what is running. That API listens on 127.0.0.1 only and needs a per-run token
(~/.flow-mcp/token).

Tools

Continuity between shots: chain_previous (this clip starts on the last frame of the previous
one), first_frame + last_frame (animate between two stills you chose), reference_images (keep a
character or product consistent). Flow's composer takes either frames or references, never both, so
when you need a start frame and a character locked together, use flow_continue, which goes through
Flow's agent mode and does both.

Output lands in ~/flow-mcp-out/<project>/scene-NN.ext.

Narration with Google's voices (optional)

flow_narrate with engine: "mac" uses your computer's own voices and works out of the box: macOS voices on a
Mac, the built-in speech voices on Windows. For Google's voices (the same ones Flow offers), get a free key from
Google AI Studio and paste it into Flow Studio → Voice → Google AI Studio
key → Save key. It's checked with Google before it's saved, and stored only on your computer. Or set
GEMINI_API_KEY. Either way, never paste the key into a chat; it would end up in the conversation history.

Behaviour and settings

• One generation at a time, with a random 25–70 second pause between them. The page carries an
  invisible reCAPTCHA; this drives the real interface at human pace and does nothing to evade it.
• Before each generation the server reads Flow's own credit quote and skips the scene if it exceeds
  max_credits (default 25).
• Environment variables: GEMINI_API_KEY, FLOW_MCP_PORT (8787), FLOW_MCP_OUTPUT,
  FLOW_MCP_HOME, FLOW_MCP_CDP_PORT (9333), FLOW_MCP_CHROME, FLOW_MCP_PAUSE_MIN_S,
  FLOW_MCP_PAUSE_MAX_S.

If something goes wrong

Licence and risk

This automates Flow's web interface. It can break whenever Google changes that interface, and
automated use may be against Google's terms of service. Use it on your own account, at your own
risk.