flow-mcp

Name: flow-mcp
Author: GTAI-1

Drives Google Flow in a local Chrome window to make videos, images, narration and captions

By GTAI-1 (individual) TypeScript Local · stdio Media AI and ML Browser automation

GitHub Website

33 popularity score ★ 534

Connect your client

Local (from source)

Add in one click

Add to Cursor Add to VS Code Add to LM Studio

Opens the app, which asks before it adds the server. Then replace each <NAME> in its settings with your value.

Or add it by command or config

FirstTerminal

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

Claude CodeTerminal

claude mcp add flow -- node '<ABSOLUTE_PATH_TO_CLONE>/dist/index.js'

Claude Desktopclaude_desktop_config.json

{
  "mcpServers": {
    "flow": {
      "command": "node",
      "args": [
        "<ABSOLUTE_PATH_TO_CLONE>/dist/index.js"
      ]
    }
  }
}

Cursor~/.cursor/mcp.json

{
  "mcpServers": {
    "flow": {
      "command": "node",
      "args": [
        "<ABSOLUTE_PATH_TO_CLONE>/dist/index.js"
      ]
    }
  }
}

VS Code.vscode/mcp.json

{
  "servers": {
    "flow": {
      "type": "stdio",
      "command": "node",
      "args": [
        "<ABSOLUTE_PATH_TO_CLONE>/dist/index.js"
      ]
    }
  }
}

Codex~/.codex/config.toml

[mcp_servers.flow]
command = "node"
args = ["<ABSOLUTE_PATH_TO_CLONE>/dist/index.js"]

Gemini CLITerminal

gemini mcp add --scope user flow node -- '<ABSOLUTE_PATH_TO_CLONE>/dist/index.js'

Settings 12

Set together: pacing
`GEMINI_API_KEY` secret	Optional: Google AI Studio key for Google narration voices. It can also be saved from the control panel. For flow_narrate.
`FLOW_MCP_OUTPUT`	Optional: Folder for downloaded and assembled media. Default `~/flow-mcp-out`.
`FLOW_MCP_HOME`	Optional: Folder holding the Chrome profile, panel token and speech models. Default `~/.flow-mcp`.
`FLOW_MCP_PORT`	Optional: Port of the local control panel and API. Default `8787`.
`FLOW_MCP_CDP_PORT`	Optional: Chrome DevTools Protocol port. Default `9333`.
`FLOW_MCP_CHROME`	Optional: Path to the Chrome executable when it is not found by itself.
`FLOW_MCP_PATIENCE_MS`	Optional: How long a call waits before handing back a task id for flow_wait. Default `45000`.
`FLOW_MCP_FFMPEG`	Optional: Path to ffmpeg. Default `ffmpeg`.
`FLOW_MCP_WHISPER`	Optional: Path to whisper.cpp's whisper-cli. Default `whisper-cli`. For flow_captions.
`FLOW_MCP_WHISPER_MODEL`	Optional: Path to a whisper model file to use instead of the downloaded ones. For flow_transcribe.
`FLOW_MCP_PAUSE_MIN_S`	Optional: Shortest pause between generations, in seconds. Default `25`.
`FLOW_MCP_PAUSE_MAX_S`	Optional: Longest pause between generations, in seconds. Default `70`.

What it does

This is a local stdio MCP server for Google Flow (flow.google.com). Claude, Codex or another MCP client can use it to make videos and images on Flow's own daily credits instead of the paid video API. It starts a Chrome window with its own profile and presses Flow's real buttons through the Chrome DevTools Protocol. Nothing is hosted and there is no browser extension.

The 20 tools in src/index.ts cover queuing image and video scenes (with first and last frames, reference images and a credit cap per scene), building reusable characters, and pulling down or trashing media that is already in a project. You can also run video-to-video edits and record narration. With FFmpeg installed it joins clips into one MP4 with music. Newer tools add captions burned into a video and word-timed transcripts. Both run whisper.cpp on your own machine and spend no Flow credits. Files are saved under ~/flow-mcp-out/<project>/ by default. A control panel at http://127.0.0.1:8787 (npm run studio) does the same jobs without an assistant.

A few things the README skips can be read in the source. A call that runs past 45 seconds returns a task id and keeps working in the background, and flow_wait picks up the result later. FLOW_MCP_PATIENCE_MS changes that limit. flow_edit and flow_continue refuse to run unless acknowledge_cost is true, because Flow shows no price before them. The first time you caption with the language left on auto, a 60 MB model is fetched to detect the spoken language.

What it needs

Runtime	Node.js 22+
Runs on	macOS, Windows
Google Flow	Free tierAny Google account gets 50 credits a day. A paid Google AI plan adds credits and 1080p downloads
Google AI Studio	Free tierOptional key, used only for Google narration voices
Also	Google Chrome A display that stays awake while it runs FFmpeg on PATH (optional, to join clips, mix music, narrate and caption) whisper.cpp whisper-cli on PATH (optional, for captions and transcripts)

Clone the repository, then run npm install and npm run build. Run npm run login once and sign in to Google by hand in the Chrome window it opens, then open a Flow project and leave that window open. On a Mac, keep the folder out of ~/Desktop, ~/Documents and ~/Downloads, or the server fails with EPERM. For captions, install whisper.cpp (brew install whisper-cpp on a Mac, whisper-cli.exe from the whisper.cpp releases on Windows). Its speech model downloads from Hugging Face on first use: 148 MB for English, 574 MB for other languages.

Limits

Platform macOS or Windows only. The README says Windows support has not yet been tried on a real PC
Limit The README warns that automated use of Flow may break Google's terms of service, and the tool can stop working when Flow's interface changes
Rate limit Runs one generation at a time with a random pause of 25 to 70 seconds by default (FLOW_MCP_PAUSE_MIN_S, FLOW_MCP_PAUSE_MAX_S)
Cost flow_edit and flow_continue get no price quote from Flow, so max_credits cannot cap them. A 4 s edit cost about 20 credits
Size cap flow_generate takes up to 100 scenes per call and flow_agent_images up to 50
Limit It needs a real, awake display. Closing the Chrome window or letting the machine sleep makes calls time out
Limit Not published to npm. It installs from a git clone and is updated with git pull and a rebuild

Who it suits

Good for someone who already has a Google account and wants an assistant to storyboard and render short films or image sets on Flow's free daily credits, then cut, narrate and caption them on their own computer. It has to drive a visible Chrome window on a Mac or Windows PC, so it will not work on a headless server or Linux, or in CI. It also depends on Flow's interface staying the same. Anyone who needs a supported, terms-safe pipeline should look at Google's paid video API, which this project names as the thing it avoids, rather than browser automation.

Tools 20

7 only read, 13 change things. A ? marks an optional parameter.

flow_status: Reports sign-in, open project, plan, credits left, the queue and the prompt playbookdetailed?: boolean
flow_generate changes: Queues image or video scenes in the open project, skipping any scene Flow prices above its capproject: stringscenes: array
flow_wait: Waits on queued jobs or a slow call's task id and returns status and file pathsjob_ids?: arraytimeout_seconds?: integer
flow_cancel changes: Drops a queued job that has not started yetjob_id: string
flow_retry changes: Puts failed jobs back in the queue with the same settings and file namesjob_ids?: array
flow_assets: Lists the images, videos and scenes already in the Flow projectkind?: enum
flow_download changes: Saves existing project media to disk without generating again, upscaled copies includedproject: stringassets: arrayquality?: enum
flow_trash changes: Moves one project item to Flow's Trash by its exact title, where it can be restoredname: string
flow_agent_images changes: Hands a batch of image prompts to Flow's Agent mode, which renders them in parallel at 0 creditsproject: stringscenes: arrayaspect_ratio?: enumdownload_quality?: enumreferences?: arrayscene_references?: object
flow_edit changes: Changes a clip already in the project from a text prompt, such as lighting, weather or removing an objectproject: stringasset: stringprompt: stringacknowledge_cost: booleandownload_quality?: enum
flow_continue changes: Makes a new clip from an existing clip's last frame with a character kept attachedproject: stringfrom_asset: stringprompt: stringattach?: arrayaspect_ratio?: enummode?: enumacknowledge_cost: booleandownload_quality?: enumforce?: boolean
flow_character changes: Creates a reusable character from a description or an image, with personality and voicename: stringdescribe?: stringimage?: stringaspect_ratio?: enumpersonality?: stringvoice?: string
flow_character_edit changes: Restyles an existing character and saves the new portrait, keeping its name and voicename: stringchange?: stringlook?: string
flow_characters: Lists the characters in the project
flow_techniques: Returns 39 film-technique prompt presets to set as a scene's techniquecategory?: enum
flow_narrate changes: Records a narration line with Google AI Studio speech or a voice installed on the computerproject: stringengine?: enumtext: stringvoice?: stringstyle?: string
flow_voices: Lists narrator voices and whether a Google key is set
flow_assemble changes: Joins clips into one MP4 with optional music, voiceover or timed voice lines, using local FFmpegproject: stringclips?: arraymusic?: stringmusic_volume?: numberclip_volume?: numbervoiceover?: stringvoice_lines?: arrayoutput_name?: stringhold_last_frame?: boolean
flow_transcribe: Transcribes a local video or audio file with start and end times for each word, using whisper.cppvideo: stringlanguage?: stringwords?: boolean
flow_captions changes: Burns spoken-word captions into a local video in one of five styles and also saves an .srtvideo: stringstyle?: enumposition?: anysize?: anycolor?: stringtext?: stringlanguage?: stringproject?: string

Popularity

33 popularity score

★ 534

GitHub stars	534	32.7 points

Measured 2026-11-07. How the score works.

Where it is published

Code	gtai-1/flow-mcp ★ 534

What it can reach

Runs	On your machine
Reaches	Drives a browser, Your account at a service, Files on your machine, The internet
Changes things	Yes: it can write, send, create or delete
Sign-in	Account credentials
Licence	Not stated
Last code change	2026-10-23

Runs on your own machine. It drives a separate Chrome profile in ~/.flow-mcp signed in to your Google account, and you do that sign-in by hand. It spends Flow credits. flow_generate skips a scene when Flow's quote is over max_credits (25 by default), but flow_edit and flow_continue get no quote and instead require acknowledge_cost set to true. It writes media under ~/flow-mcp-out and can move project items to Flow's Trash. FFmpeg and whisper.cpp run locally, and speech models download from Hugging Face on first use. The control panel and API listen on 127.0.0.1 and use a token file. The README warns that automated use may go against Google's terms of service.

Over time

GitHub stars 534 +394 (+281 %)

534140

13 Oct 20267 Nov 2026

Popularity score 33 +7 (+27 %)

3326

13 Oct 20267 Nov 2026

What is rising across the directory

Sources

Page checked 2026-10-29.

Badge for your README

Shows this server's rank in its category, and stars for a server that runs on your machine. It updates every hour.

MarkdownREADME.md

[![flow-mcp on EveryMCPServer](https://everymcpserver.com/badge/flow-mcp.svg)](https://everymcpserver.com/servers/flow-mcp)

Connect your client

Add in one click

Or add it by command or config

Settings 12

What it does

What it needs

Limits

Who it suits

Tools 20

Similar servers

gflow-cli

MCP Image Generator

Browser Use Cloud MCP

MeiGen AI Design MCP

Browser Use

comfyui-mcp