Skip to content
Back to search

flow-mcp

Drive Google Flow from Claude, Codex or a local control panel, on Mac or Windows — using your Google AI subscription credits instead of the pay-per-use video API. No browser extension.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/GTAI-1/flow-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/GTAI-1/flow-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/gtai-1--flow-mcp/badge.svg)](/listings/gtai-1--flow-mcp)

HTML

<a href="/listings/gtai-1--flow-mcp"><img src="/api/listings/gtai-1--flow-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 270 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # flow-mcp
  2. Drive **Google Flow** (flow.google.com) from Claude, Codex or any other MCP app, or from a local control
  3. panel, using Flow's own credits (free with any Google account: 50 a day), not the pay-per-use video API.
  4. It is a small program that runs on your own machine. It opens its own Chrome window, signs in
  5. as you, and clicks Flow's real buttons. There is no browser extension, no hosted service and no
  6. account to create.
  7. ```
  8. Claude / Codex ──stdio──> flow-mcp ──Chrome DevTools Protocol──> Chrome (its own profile) ──> Flow
  9. ```
  10. **MCP** = Model Context Protocol, the standard that lets Claude use outside tools.
  11. New here? [GETTING-STARTED.md](GETTING-STARTED.md) takes you from nothing to your first video, step by step, and
  12. [OVERVIEW.md](OVERVIEW.md) explains what it does in plain English, with no code names.
  13. ---
  14. ## What you need
  15. | | |
  16. |---|---|
  17. | **macOS or Windows 10/11** | Developed and tested on macOS. Windows is supported (Chrome, the Recycle Bin and the panel launcher all have Windows versions), but it hasn't been run on a real PC yet, so please report anything that breaks |
  18. | **Node.js 22 or newer** | `node --version` |
  19. | **Google Chrome** | Any recent version |
  20. | **A Google account** | Free. Flow gives every account 50 credits a day; a paid Google AI plan adds more and unlocks 1080p downloads. Developed on a Pro plan |
  21. | **FFmpeg** *(optional)* | Mac: `brew install ffmpeg` · Windows: `winget install Gyan.FFmpeg`. Needed only to join clips, mix music or record narration |
  22. | **A Google AI Studio key** *(optional, free)* | Only for the Google narration voices. See below |
  23. | **whisper.cpp** *(optional, free)* | Only for captions: it hears the words, on your computer. Mac: `brew install whisper-cpp` · Windows: `whisper-cli.exe` from [the whisper.cpp releases](https://github.com/ggml-org/whisper.cpp/releases), on your PATH. The speech model it needs downloads by itself the first time you caption a video: 148 MB for English, 574 MB for any other language |
  24. A display must stay awake: the Chrome window is really being driven, so the machine cannot be
  25. headless or asleep mid-run.
  26. ---
  27. ## Install
  28. ```bash
  29. git clone https://github.com/GTAI-1/flow-mcp.git
  30. cd flow-mcp
  31. npm install
  32. npm run build
  33. ```
  34. > **Mac: do not put this folder in `~/Desktop`, `~/Documents` or `~/Downloads`.** macOS protects those
  35. > folders, and apps that launch the server from there can be refused permission to read its own
  36. > files (`EPERM: operation not permitted`). `~/flow-mcp` or anywhere in your home folder is fine.
  37. >
  38. > **Windows: keep it out of folders OneDrive syncs** (often Desktop and Documents), where files can be held
  39. > online-only. `C:\Users\<you>\flow-mcp` is fine.
  40. Then sign in, once:
  41. ```bash
  42. npm run login
  43. ```
  44. That opens the dedicated Chrome window. Sign into Google by hand, open (or create) a Flow project,
  45. and leave the window open. The program never types your password; it only uses the session you
  46. created. That Chrome profile lives in `~/.flow-mcp/chrome-profile` and is separate from your
  47. everyday browser.
  48. ---
  49. ## Connect it to Claude, Codex or Antigravity
  50. **Claude Code**
  51. ```bash
  52. claude mcp add --scope user flow -- node /absolute/path/to/flow-mcp/dist/index.js
  53. ```
  54. `--scope user` makes it available in every folder; the default (`local`) only works in the folder you ran it from.
  55. **Claude Desktop**: add to `claude_desktop_config.json` (Mac: `~/Library/Application Support/Claude/`, Windows:
  56. `%APPDATA%\Claude\`). On Windows, write the path with doubled backslashes, like
  57. `"C:\\Users\\you\\flow-mcp\\dist\\index.js"`:
  58. ```json
  59. { "mcpServers": { "flow": { "command": "node", "args": ["/absolute/path/to/flow-mcp/dist/index.js"] } } }
  60. ```
  61. **Codex**: add to `~/.codex/config.toml` (on Windows, `%USERPROFILE%\.codex\config.toml`):
  62. ```toml
  63. [mcp_servers.flow]
  64. command = "node"
  65. args = ["/absolute/path/to/flow-mcp/dist/index.js"]
  66. ```
  67. Or run `codex mcp add flow -- node /absolute/path/to/flow-mcp/dist/index.js`. No timeout setting is needed:
  68. Codex, like most MCP apps, gives up on a tool call after 60 seconds, so any call that runs longer than about
  69. 45 seconds (creating a character, a 1080p download) answers with a task id instead and keeps working, and
  70. `flow_wait` collects the result.
  71. **Antigravity** (Google's coding app): add a `flow` entry to `mcp_config.json`. On a Mac it lives in
  72. `~/.gemini/antigravity/`; you can also open it from the agent panel's **…** menu → **Manage MCP Servers** →
  73. **View raw config**. Keep any servers already listed and add this one beside them:
  74. ```json
  75. { "mcpServers": { "flow": { "command": "node", "args": ["/absolute/path/to/flow-mcp/dist/index.js"] } } }
  76. ```
  77. **Other MCP apps** (Cursor, VS Code and others) take the same command and arguments in their own MCP
  78. settings. ChatGPT in the browser or the ChatGPT app can't use it: its connectors only reach servers on
  79. the internet, and this tool has to run on your own computer to drive your Chrome window.
  80. Developed and tested with Claude. Codex and Antigravity speak the same protocol, so they should work the
  81. same way, but neither has been tried yet, so please report how it goes. Running two of them at once is safe:
  82. the first one started drives Flow, and the others pass their requests to it.
  83. Restart the app, then ask it: *"check my Flow session"*. You should get your plan and credit balance
  84. back. Everything after that is plain English; you never type tool names.
  85. ---
  86. ## Your first film
  87. Nothing below costs a credit until step 4, and the assistant asks before spending.
  88. 1. **Check the session.** *"Check my Flow session."* This confirms sign-in, plan and credits.
  89. 2. **Make a character.** *"Create a character called Pip, a small lamplighter in a flat cartoon style."*
  90. Flow draws the portrait. Free.
  91. 3. **Draw the key frames.** *"Draw three stills with Pip: a dark rooftop, him lighting a lamp, the
  92. whole hillside glowing. Match each one to the last."* Free: stills cost nothing, so get the look
  93. right here before spending.
  94. 4. **Shoot it.** *"Turn those into three 10-second shots, each starting where the last one ended,
  95. 720p, no more than 15 credits each."* This spends credits. The price is read from Flow's own
  96. quote first and the scene is skipped if it is over your cap.
  97. 5. **Narrate it.** *"Record this line with a warm documentary voice."* Free, any length.
  98. 6. **Cut it.** *"Join the three shots under the narration, don't freeze the last frame."*
  99. The finished file lands in `~/flow-mcp-out/<project>/`.
  100. ---
  101. ## The control panel
  102. The same features, without an AI assistant in the loop:
  103. ```bash
  104. npm run studio # then open http://127.0.0.1:8787
  105. ```
  106. or double-click **Flow Studio.command** (Mac) or **Flow Studio.cmd** (Windows).
  107. Eight tabs, in the order you would use them:
  108. - **Cast**: reusable characters. Create them, edit them in place, or build one from a picture.
  109. - **Frames**: free stills, with *match previous frame* to keep a set on-model.
  110. - **Shots**: paid clips, with first/last frames, chaining, a live credit estimate, and a card that
  111. continues a finished clip from its own last frame.
  112. - **Voice**: free narration with Kokoro (the default: 28 voices, runs on your computer, no key) or Google's
  113. voices. Your saved narrations are listed
  114. here to play or delete, and there's a field for your Google AI Studio key (checked with Google, stored
  115. only on your computer; never paste it into a chat).
  116. - **Restyle**: change a clip you already have.
  117. - **Cut**: join any videos into one film, in the order you pick. Upload one, or choose from films you've
  118. already made. Add a narration (from your saved ones or an upload) and music, and turn the clips' own
  119. sound down so the narration sits on top.
  120. - **Captions**: put the spoken words on screen, the way short-form videos do, on wide or vertical videos.
  121. Pick a video and the language spoken in it (about 100 languages, or Detect automatically), choose a
  122. style (Bold pop, Highlight, Word by word, Clean, Boxed), where it sits (bottom,
  123. middle, top, an exact height, or tap the preview), its size (a slider), its letters (normal, CAPS or lowercase) and
  124. highlight colour, and see it on a real frame of your video before anything is made. Fix any misheard
  125. word in the text box and it keeps its timing; press Enter to start a new caption. Saves `<name>-captions.mp4` plus an `.srt` for YouTube.
  126. Everything happens on your computer; nothing is uploaded.
  127. - **Library**: everything in your Flow project. Download it again for free (a scene comes down as one
  128. finished film, not loose clips), or move it to Flow's Trash.
  129. A progress monitor and a gallery of your saved work sit alongside. The gallery shows stills or clips
  130. on the tabs that use them. On a wide screen, each side scrolls on its own. Two kinds of delete, clearly
  131. labelled: **Move to the Mac's Trash / Recycle Bin** removes a file from your computer; **Move to
  132. Flow's Trash** removes it from your Flow project only. Both can be undone.
  133. The panel ships with the repo but is not started for you: run `npm run studio` when you want it.
  134. Opening `studio/index.html` as a plain file does nothing; the page needs the server behind it, and
  135. says so in red if you try.
  136. Claude's own process serves the same panel while it runs. Whichever process starts first owns the
  137. Chrome tab and the job queue; the other talks to it over a local API, so Claude and the panel always
  138. agree on what is running. That API listens on 127.0.0.1 only and needs a per-run token
  139. (`~/.flow-mcp/token`).
  140. ---
  141. ## Tools
  142. | Tool | Purpose |
  143. |---|---|
  144. | `flow_status` | Session state (signed in, project open, plan, credits left), queue, pacing, prompt playbook |
  145. | `flow_generate` | Queue scenes: prompt, image or video, model, aspect, duration, resolution, variants, first/last frame, reference images, `max_credits` cap |
  146. | `flow_wait` | Wait for jobs, or for the task id of a slow call; returns file paths and results. Answers within about 40 s, so call again until `finished` is true |
  147. | `flow_cancel` | Cancel a job that has not started |
  148. | `flow_retry` | Re-queue failed jobs with the same settings and file names (a failed tile is first retried inside Flow with its own free Retry button: `retries`, default 1) |
  149. | `flow_assets` | List images and videos already in the Flow project (usable as `asset:<title>`) |
  150. | `flow_download` | Download existing project media without regenerating. Free, including the 1080p / 2K upscale. A scene comes down as one stitched film. `collection` brings a whole Flow collection down as one ZIP of originals |
  151. | `flow_trash` | Move an image, video or scene in the Flow project to Flow's Trash, where it can be restored. Exact title only; refuses if two items share it; never deletes permanently |
  152. | `flow_agent_images` | Fast image batch: hands up to 50 scenes to Flow's own Agent mode, rendered in parallel (20 images in ~204 s), 0 credits. The finished images are gathered into a Flow collection and come down as ONE ZIP of originals, checked against the batch and downloaded again if one is missing; if that step fails, the batch stops and says where the images are, and never downloads them one by one. If Agent mode cannot be used at all, the batch stops with the reason. Each image is matched back to its scene by its stored prompt, so file numbers are right in any finish order. Scenes the agent drops are re-asked of it (up to 2 rounds), then re-run one by one. `references` attaches characters, places and objects once in the agent's composer (like its + button), and `scene_references` says which scenes use which, so a whole story stays on-model; scenes made one by one keep their references |
  153. | `flow_edit` | Video-to-video edit of a clip already in the project (relight, weather, remove objects). Flow shows no quote first; about 20 credits for a 4 s clip |
  154. | `flow_continue` | Start a clip from the last frame of an existing one **with a character or your avatar still attached**. The composer allows a start frame or attached characters, never both, so this drives Flow's agent mode, which does both. No quote beforehand |
  155. | `flow_character` | Create a reusable character from a description (Flow draws the portrait) or an image, with a personality and a stock voice; use it as `asset:<name>` |
  156. | `flow_character_edit` | Restyle an existing character in place (free) and save the new portrait; name, personality and voice are kept, so every scene referencing it updates. Pass `look` with the updated description; with only a name it re-saves the current portrait |
  157. | `flow_characters` | List the project's characters |
  158. | `flow_techniques` | 39 film-technique prompt presets (camera moves, product shots, transitions, image commands); pass an id as a scene's `technique` |
  159. | `flow_narrate` | Free narration audio, any length: `kokoro` (the default, a voice that runs on your computer, 28 voices and a `speed`), or `gemini` (Google AI Studio text-to-speech, with the same voices Flow has, plus a `style` note; falls back to Kokoro when the daily limit is used up) |
  160. | `flow_voices` | Narrator voices available, whether Kokoro's model is downloaded yet, and whether a Google key is set up |
  161. | `flow_captions` | Burn spoken-word captions into any video, landscape or vertical, in one of five styles, at any height and size, in normal, capital or lowercase letters, in about 100 languages; returns the transcript so a misheard word can be fixed and the call repeated (local whisper.cpp, Chrome and FFmpeg, no credits) |
  162. | `flow_transcribe` | Hear the words in any video or audio on your computer, with each word's start and end time (local whisper.cpp, free) |
  163. | `flow_assemble` | Join clips into one MP4 (a project's clips, or any you list, in order) with optional music and voiceover, and separate volume for the clips' own sound. A voiceover can also be built line by line (`voice_lines`), each line cut from a take and placed at its own moment, for narration timed to on-screen titles (local FFmpeg, no credits) |
  164. **Continuity between shots:** `chain_previous` (this clip starts on the last frame of the previous
  165. one), `first_frame` + `last_frame` (animate between two stills you chose), `reference_images` (keep a
  166. character or product consistent). Flow's *composer* takes either frames or references, never both, so
  167. when you need a start frame **and** a character locked together, use `flow_continue`, which goes through
  168. Flow's agent mode and does both.
  169. Output lands in `~/flow-mcp-out/<project>/scene-NN.ext`.
  170. ### Narration voices
  171. `flow_narrate` uses **Kokoro** by default: a free voice that runs on your own computer, with no key, no daily
  172. limit and no length cap. Pick any of its 28 English voices (American and British) and a speed. The first take
  173. downloads its model once (326 MB, about a minute); after that a take records in a couple of seconds.
  174. #### Google's voices (optional)
  175. For Google's voices (the same ones Flow offers), get a free key from
  176. [Google AI Studio](https://aistudio.google.com/apikey) and paste it into **Flow Studio → Voice → Google AI Studio
  177. key → Save key**. It's checked with Google before it's saved, and stored only on your computer. Or set
  178. `GEMINI_API_KEY`. Either way, never paste the key into a chat; it would end up in the conversation history.
  179. ---
  180. ## Behaviour and settings
  181. - One generation at a time, with a random 25–70 second pause between them. The page carries an
  182. invisible reCAPTCHA; this drives the real interface at human pace and does nothing to evade it.
  183. - Before each generation the server reads Flow's own credit quote and skips the scene if it exceeds
  184. `max_credits` (default 25).
  185. - Any Google account language works. The server finds Flow's buttons by their English names, so its
  186. Chrome window always shows Flow in English (it adds `?hl=en` to the address). Your account's own
  187. language setting is never changed, and prompts can be written in any language.
  188. - Environment variables: `GEMINI_API_KEY`, `FLOW_MCP_PORT` (8787), `FLOW_MCP_OUTPUT`,
  189. `FLOW_MCP_HOME`, `FLOW_MCP_CDP_PORT` (9333), `FLOW_MCP_CHROME`, `FLOW_MCP_PAUSE_MIN_S`,
  190. `FLOW_MCP_PAUSE_MAX_S`.
  191. ## If something goes wrong
  192. | Symptom | Cause |
  193. |---|---|
  194. | Mac: the server will not start, `EPERM: operation not permitted` | The folder is in a macOS-protected location. Move it out of `~/Desktop`, `~/Documents` or `~/Downloads` and update the path in your Claude config |
  195. | *"Not signed in"* or *"no project open"* | Run `npm run login`, sign in, open a Flow project, leave the window open |
  196. | A clip generated but no file arrived | The media is still in Flow. `flow_download` pulls it back for nothing. Never re-generate and pay twice |
  197. | Everything times out | The Chrome window was closed, or the machine slept. Reopen it with `npm run login` |
  198. ---
  199. ## Updating
  200. Tell your assistant: *"Update Flow MCP: in my flow-mcp folder, run git pull, then npm install, then npm run
  201. build."* Then fully quit and reopen your assistant app so it loads the new version.
  202. ---
  203. ## Licence and risk
  204. This automates Flow's web interface. It can break whenever Google changes that interface, and
  205. automated use may be against Google's terms of service. Use it on your own account, at your own
  206. risk.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.