Google Flow MCP
Mitanshp5/Google-Flow_MCP
Automação segura de imagem/vídeo via Google Flow sem compartilhar credenciais
Ver no GitHubServidor MCP multiplataforma que automatiza geração de imagens e vídeos via Google Flow através de um perfil Chrome autenticado, sem compartilhar credenciais com o agente IA. Fornece 31 ferramentas validadas para controlar pipelines de produção com segurança e controle de gastos.
Instalação
npx convez-ai Mitanshp5/Google-Flow_MCP1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Gerar personagens e folhas de referência visual de forma consistente
- Criar storyboards e sheets de vídeo automaticamente via FFmpeg
- Automatizar pipelines de produção de conteúdo visual com agentes IA
- Controlar gastos de crédito e revisar qualidade de saída programaticamente
Veredito

MCP robusto e bem arquitetado para produção visual em escala. Implementação séria com controles de segurança, suporte multiplataforma e ferramentas granulares — adequado para equipes que precisam automatizar geração de mídia via Google Flow de forma governada.
README
A tradução para o português deste README ainda está na fila.
Google Flow Browser MCP
An MCP (Model Context Protocol) server that lets an AI agent drive
Google Flow (flow.google.com)
through your own logged-in Chrome profile — generating images, videos,
characters, and multi-shot scenes — without ever sharing your Google credentials with
the agent.
This server supports Windows, macOS, and Linux out of the box using unified npm commands that automatically dispatch platform-specific execution.
Visual Showcase
Generated outputs and automated FFmpeg quality-review artifacts from real Flow workflows driven by this MCP:
How it works
- Chrome is launched with
--remote-debugging-port(Chrome DevTools Protocol / CDP) using a real Chrome profile that's already signed in to your Google account. - The MCP server (
src/index.js) connects to that Chrome instance via Playwright'sconnectOverCDPand drives the Google Flow web app — filling prompts, inspecting live credit quotes, observing network acknowledgements, and reading results. - Your AI agent (Claude / OpenCode / any MCP client) talks to the MCP
server over stdio using 31 Zod-validated tools (
flow_generate_image,flow_generate_video,flow_create_character,flow_script_*, etc.).
Core reliability & safety guarantees
- Prepare-Only by Default (
auto_confirm = false) & Story Video Budget: Image, video, and character generation fills prompts, models, aspect ratios, and@mentions, then returnsready_for_confirmation. Image and character generation are always free (0credits) and are never blocked for credit reasons. Paid video credit spend requires explicitflow_generate_confirm(orconfirm_generate: true) gated bymax_credits, a 50-credit default story/project budget (calculates required story credits up front and prompts for explicitallocatedBudgetapproval if the story needs more), and a persistent project credit ledger. - Account Safety Circuit Breaker (
src/domain/account-circuit-breaker.js): Automatically detects unusual-activity, CAPTCHA, and rate-limit signals, persisting cooldowns insecurity/account-cooldowns.json(1800sunusual activity,900sCAPTCHA gate,300srate limit). Paid submissions fail closed during active holds while read-only inspection (flow_status,flow_script_status) stays available. - Passive RPC Telemetry (
src/domain/live-submission.js): Passively observesbatchexecuteRPC traffic (ogiZ0bfor images;eb1hJf,YhhmEf,nprQif,MZZa6bfor video) to extractoperationIdsandmediaIds, cross-checked against independent Flow DOM verification. Never invokes private RPCs directly or performs blind retries onsubmission_unknown.
Because the agent never touches your Google password — it only sends commands to a browser that's already logged in — there's no credential sharing involved.
Prerequisites
- Node.js >= 20.11 (see
enginesinpackage.json; LTS recommended) - Google Chrome installed normally (Playwright connects to your real Chrome via CDP — it does not need its own bundled browser for this)
- A Google account already signed in to a Chrome profile (e.g. "Default" or "Profile 1" — any profile works, you just need to tell the config which one)
- (Optional) OpenCode if you want to register this MCP server with it
Setup
1. Clone and install dependencies
git clone https://github.com/Mitanshp5/Google-Flow_MCP.git
cd Google-Flow_MCP
npm install
npm install will also download Playwright's browser binaries. This project
doesn't use Playwright's bundled Chromium though — it connects to your real
installed Chrome.
2. Find your Chrome profile
You need a Chrome profile that's already signed in to the Google account you want Flow to use.
- Open Chrome and go to
chrome://version - Look at Profile Path — note the User Data directory and Profile folder name (e.g.
Default,Profile 1,Profile 2).
Default locations by platform:
- Windows:
- Executable:
C:\Program Files\Google\Chrome\Application\chrome.exe(Auto-detected) - User Data:
C:\Users\<username>\AppData\Local\Google\Chrome\User Data
- Executable:
- macOS:
- Executable:
/Applications/Google Chrome.app/Contents/MacOS/Google Chrome(Auto-detected) - User Data:
/Users/<username>/Library/Application Support/Google/Chrome
- Executable:
- Linux:
- Executable:
/opt/google/chrome/chromeor/usr/bin/google-chrome(Auto-detected) - User Data:
/home/<username>/.config/google-chrome
- Executable:
If you don't have a profile signed in yet, sign in to your Google account in
any Chrome profile first (Settings → You and Google → Sign in).
⚠️ Close all running Chrome windows for that profile before using this tool — Chrome locks its profile directory while running, so the MCP server's "direct + CDP" launch mode copies the profile into a temporary directory to avoid conflicts. If Chrome is running with that profile while you start the scripts, you may see a "profile already in use" issue.
3. Create your config file
Copy the example config and edit it:
Windows (PowerShell):
copy config\flow.config.example.json config\flow.config.json
macOS / Linux:
cp config/flow.config.example.json config/flow.config.json
Open config/flow.config.json and set at minimum:
{
"expectedAccount": null,
"chromeProfile": "Default"
}
Note: You only need to set chromeUserDataDir and chromeExecutable if Chrome is installed in a custom location, as the server will otherwise auto-detect them for your current platform.
Unified Commands
This project uses a Node.js dispatcher script under the hood, allowing you to run the same npm commands on Windows, macOS, or Linux. The runner will automatically execute the correct scripts (.ps1 for Windows, .sh for Unix).
1. Start Chrome with CDP debugging
npm run start-browser
This launches Chrome with your configured profile and --remote-debugging-port=9222. A Chrome window will open — leave it running.
2. Start the MCP server (optional manual test)
In a separate terminal:
npm run start-mcp
This checks Node is installed, checks Chrome's CDP port is responding, and runs the MCP server. Press Ctrl+C to stop it.
3. Connect to AI Agents
You can automatically configure OpenCode and Gemini CLI in one step:
npm run register
This will automatically find their configuration files and add the Google-Flow MCP server.
(You can also target specific clients: npm run register -- --opencode or --gemini)
Claude Desktop
Currently, Claude Desktop requires manual configuration:
Add the following to your claude_desktop_config.json (run npm run build first — dist/ is what ships):
{
"mcpServers": {
"Google-Flow": {
"command": "node",
"args": ["/absolute/path/to/Google-Flow_MCP/dist/index.js"]
}
}
}
Cursor (Codex) Currently, Cursor requires manual UI configuration:
- Open Cursor Settings > Features > MCP.
- Click + Add New MCP Server.
- Name:
Google-Flow - Type:
command - Command:
node /absolute/path/to/Google-Flow_MCP/dist/index.js(runnpm run buildfirst;src/index.jsworks for dev only)
4. Verify everything end-to-end
With Chrome running (step 1), run unit tests plus a live smoke test:
npm test # vitest unit tests (validation, queue, sanitizers)
npm run test:smoke # flow_connect over stdio (needs Chrome running)
npm run build # bundles src/ -> dist/ (required before register)
Typical workflow
npm run start-browser— once per session, leave the Chrome window open (or reuse an already-open Chrome:flow_list_browser_targetsfinds its CDP port,flow_connecttakescdpPort)- Your AI agent (with this MCP registered) calls:
flow_connect— attach to the running Chrome (also refreshes the live model catalog)flow_account_check— confirm the right Google account is signed inflow_list_models— list live video/image models, ratios, durations (call once per session before generating; cache reportsstale/cacheAgeMs)flow_create_project— mint a brand-new project (never reuses/renames an existing one; pin it viaproject_url)flow_generate_image— prepare (or withauto_confirm:true, generate) images in a Flow projectflow_create_character— create reusable characters (optionalarchetypestarter card)flow_generate_video— prepare (or withconfirm_generate:true, paid-generate) videos, optionally referencing previously generated images/characters viaingredients(@namereferences)flow_generate_confirm— live-click Generate for a verifiedready_for_confirmationpreparation (images/characters are 0 credits and never credit-blocked; video is gated by storyallocatedBudgetandmax_credits: Omni ~10, Veo Fast/Lite ~20, Veo Quality ~50; never confirmsprepared_unverified)flow_rename_character— rename a character in its detail page (never the project title)flow_rename_image— rename one image by exact title or media ID (never the project title)flow_list_mention_options— see what images/characters are available to reference by name
The MCP server automatically creates a Google Flow project on first use and reuses it for the rest of the session (tracked by project ID), so everything ends up in one place instead of a new project per request.
Google Flow production workflow
For directed multi-shot videos, start with Google Flow Production. It includes brief and shot-plan templates, continuity checks, fifteen on-demand creative style cards, prepare-only tool examples, and final-delivery checks. The workflow uses the existing MCP tools; it does not add a renderer or change credit safeguards.
Layer 2 Stateful Production Capabilities
- DAG Scene Chaining & Continuity State (
src/script/): Plan scripts withflow_script_create..flow_script_resumeusingROOT,CONTINUATION, andINSERTshot edges, 7 entity types (character,location,prop,visual_asset,creature,generic_troop,faction), automatedCONTINUITY_BREAKvalidation, last-frame carry-forward (start_frame/end_frame), andsceneChainstracking ingetStoryStatus. - Selective Prompt Scaffolding (
subject,setting,audio,negative,include_standard_negative):flow_generate_imageandflow_generate_videocompose structured prompts insrc/utils/prompt.js, gating audio instructions specifically to Veo video models. - Advisory Video QA (
src/media/video-reviewer.js): Extracts FFmpeg 4×2 contact sheets (extractVideoContactSheet()) and evaluates 6 weighted quality dimensions (VIDEO_REVIEW_WEIGHTSsumming to1.00) viaevaluateVideoReview()andgenerateAdvisoryFixGuide(). Output is strictly advisory (advisoryOnly: true,requiresAuthorizationForRegen: true). - Continuity-Safe FFmpeg Assembly (
scripts/assemble-video.mjs): Standalone local FFmpeg script normalizing clips to H.264yuv420pand 48kHz stereo AAC audio (--inputs,--output,--manifest,--transition auto|cut|xfade,--xfade-duration,--skip-lead,--narration,--music,--extract-frames,--report). Automatically suppresses lead-frame trimming onCONTINUATIONshots so frame-chained cuts remain seamless.
In an agent client with this repository available, ask:
Read
skills/google-flow-production/SKILL.mdand use it to plan my video. Confirm the brief and shot plan first; do not spend credits until I authorize a budget.
The complete skill folder is also included in the npm package. Clients that do not automatically discover repository skills must read its SKILL.md explicitly, or you can copy the complete skills/google-flow-production/ folder into your client's supported skill directory. Keep its relative references, templates, and third-party notice together. Installing the MCP alone does not automatically activate the skill.
Model settings must match both the advertised tool schema and the selected model's verified live UI. Frames and Ingredients remain separate video modes. Script tools provide local planning/candidate review, not autonomous remote rendering. There is no MCP timeline editor or exporter; arbitrary local assembly requires an explicitly planned, separately authorized edit.
Available tools
| Tool | Purpose |
|---|---|
flow_connect | Connect to / launch Chrome via CDP, optionally open Flow (cdpPort reuses an already-open browser) |
flow_disconnect | Close the browser connection |
flow_list_browser_targets | Probe local CDP ports for a listening Chrome (no browser needed) |
flow_create_project | Mint a brand-new project (never reuses/renames; pin via project_url) |
flow_list_projects | List known projects from the local registry (no browser needed) |
flow_open | Navigate the connected browser to a Flow URL without reconnecting |
flow_status | Report current connection/page status |
flow_account_check | Identify the signed-in Google account; enforce expectedAccount only if configured |
flow_discover_ui | Navigate to a Flow page and dump interactive elements (debugging) |
flow_generate_image | Generate image(s) from a prompt in the current project (free — 0 credits; prepare-only by default; auto_confirm:true submits immediately) |
flow_generate_video | Generate video(s), optionally with ingredients/use_character/use_scene references (prepare-only by default; confirm_generate:true spends credits) |
flow_generate_confirm | Live-click Generate for a verified ready_for_confirmation job, gated by max_credits (never confirms prepared_unverified) |
flow_rename_character | Rename a character in its detail page (never the project title) |
flow_rename_image | Rename an existing image by exact name or asset_id, with new_name and optional project scope |
flow_list_models | List video/image models, ratios, durations from Flow UI (live) or cache |
flow_download_latest | Download an existing asset in the open project; returns choices when newest cannot be verified |
flow_create_character | Create a new character (name + description + optional archetype starter + reference images) |
flow_import_character | Import a character from a saved JSON file |
flow_open_characters | Open the Characters page for a project |
flow_list_mention_options | List images/characters available for @name references |
flow_open_tools_gallery | Open Flow's Tools gallery |
flow_use_tool | Use an arbitrary tool from the Tools gallery |
flow_screenshot | Take a debug screenshot of the current page |
flow_queue_status | Check the status of queued generation jobs |
flow_queue_reset | Forcefully reset the job queue if a job is stuck in "running" state |
flow_script_create | Create a structured script, continuity bible, DAG, and policy in immutable revision storage (zero credit spend) |
flow_script_update | Update script brief, bible, scenes, or shots under CAS revision control and compute DAG invalidations |
flow_script_status | Query script continuity status, sceneChains, shot readiness, blocking prerequisites, and next steps |
flow_script_review | Submit digest-bound human/director reviews, score candidates, or update reference/pack selections |
flow_script_run | Stage bounded local image-candidate intents, local_import assets, or review-artifacts contact sheets |
flow_script_resume | Resume/advance a script run within its existing bounded candidate and time budget |
Configuration reference
All settings live in config/flow.config.json (copy from flow.config.example.json). Key fields:
| Field | Description | Default |
|---|---|---|
expectedAccount | Optional email restriction; null accepts any positively identified signed-in account | null |
chromeExecutable | Full path to chrome executable (optional, auto-detected) | auto-detected |
chromeUserDataDir | Path to Chrome's "User Data" folder | auto-detected per-OS |
chromeProfile | Profile folder name (e.g. Default, Profile 1) | Default |
cdpPort | Chrome DevTools Protocol port | 9222 |
flowUrl | Base Google Flow URL | https://flow.google.com/ |
headless | Run Chrome headless (not recommended — Flow needs visible browser) | false |
jobTimeoutMs | Watchdog: max time a job may stay running before auto-fail | 300000 |
jobHistoryLimit | Bounded queue history kept in flow_queue_status | 50 |
actionDelayMs | Delay between automated UI steps | 800 |
agentResponseTimeoutMs / generationTimeoutMs | Agent dialog window / generation wait | 5000 / 120000 |
downloadWaitMs | Wait for download to complete | 30000 |
imageModels / videoModels | Display name → internal model ID maps (merged with live discovery) | see example config |
ratios / videoRatios / durations (4s,6s,8s,10s) / quantities | Allowed generation parameters | see example config |
Env overrides win over the file: FLOW_URL, FLOW_EXPECTED_ACCOUNT, FLOW_CHROME_PROFILE, FLOW_CDP_PORT, FLOW_HEADLESS, FLOW_JOB_TIMEOUT_MS, FLOW_CHROME_EXECUTABLE, FLOW_CHROME_USER_DATA_DIR, FLOW_HOME.
Troubleshooting
"Chrome not found"
Make sure Chrome is installed normally. If it is in a custom path, set chromeExecutable in config/flow.config.json.
"Chrome profile not found"
Double-check chromeUserDataDir + chromeProfile against chrome://version in your browser.
"CDP port 9222 not responding"
Run npm run start-browser first and leave that Chrome window open.
Google sign-in gets blocked ("This browser may not be secure")
This is why the server connects to your existing signed-in Chrome profile. Ensure chromeUserDataDir / chromeProfile points to the profile you logged in with.
The agent creates a new Flow project every time
The server tracks one project per session by ID and reuses it. If this happens, check the logs for Session project no longer reachable and start a fresh session.
Downloads return "No download button found on current page" or project_required
Pass {"project_url":"https://flow.google.com/project/<your-project-id>"} to flow_download_latest to open the existing project and download from it directly. The tool briefly waits for its media library to load. It never creates a project or generates new media. Alternatively, open the project with flow_open first, then call flow_download_latest without project_url to keep the current project and composer intact.
If the result is ambiguous, choose the intended asset from the returned assets/choices, then call flow_download_latest with {"asset_id":"<exact-id-from-choices>"} (and the same project_url if needed). The tool does not guess newest from grid position. If it returns no_visible_assets inside the correct project, make the completed asset visible and retry. If that still fails, report your package version and a screenshot with private details hidden.
Project layout
Core runtime modules are organized across src/browser/ (CDP connection, UI transaction lock, account check), src/domain/ (account-circuit-breaker.js, live-submission.js, commit-prepared-generation.js, submission-policy.js), src/media/ (video-reviewer.js), src/script/ (DAG planning & continuity validation), src/storage/, scripts/assemble-video.mjs (local FFmpeg delivery CLI), and docs/assets/ (README visuals & showcase frames).
config/
flow.config.example.json # template — copy to flow.config.json (gitignored)
flow.models.json # live model catalog cache (gitignored, regenerated)
selectors.map.json # self-healing selector cache from flow_discover_ui (gitignored)
scripts/
run.js # OS-independent dispatcher (prefers pwsh on Windows)
start-browser.ps1 / .sh # launch Chrome with CDP debugging
start-mcp.ps1 / .sh / .bat # run the MCP server (manual check)
register.ps1 / .sh # register this server (prefers dist/, falls back to src/)
test-flow-image.ps1 / .sh # quick flow_connect smoke test (npm run test:smoke)
src/
index.js # MCP server entry point (validated with zod, fail-closed errors)
browser/ # Chrome/CDP connection (non-destructive reuse, liveness)
navigation/ # project registry, @ mention references, live model discovery
queue/ # single-job queue with watchdog + bounded history
tools/ # one file per MCP tool
utils/ # config, logger (stderr-only), screenshots, sanitize, validate,
# prompt QC, dynamic model universe, selector registry
tests/ # vitest unit tests: sanitize, validate, job-queue,
# file-manager, video-quality, dynamic-catalog, prompt-bar
Safety notes
- This server only automates a browser you already control and are signed into — it does not store, transmit, or need your Google credentials.
- Chrome is launched without the unsupported
--disable-blink-features=AutomationControlledflag. Direct launches use a temporary copy of your configured profile; Google may still require manual sign-in or additional verification. The server does not bypass those checks. - Video generation consumes Google Flow credits; image generation and character creation are free (
0credits) and are never blocked by credit checks, caps, or credit-warning banners. Tools default to safe "prepare only" behavior (auto_confirm: false; video live-generate additionally requiresconfirm_generate: true).flow_create_characteralso defaults tofalse. - Account-level safety protections (unusual-activity / CAPTCHA / rate-limit circuit breaker) still apply uniformly to protect your Google account.
flow_disconnectnever kills your personal Chrome tabs — it detaches unless the server launched Chrome itself.flow_account_checkis fail-closed: without positive evidence it returnsverified:false, needsManualCheck:true(neverassumed:true).config/flow.config.jsonis gitignored — do not commit it. Runtime caches (flow.models.json,selectors.map.json,flow.projects.json) are gitignored too.- Runtime records (
project-credit-budgets/,operations/,consumed-children/,journal/, and generatedscripts/*/state) stay local. Preserve them when cleaning the workspace: deleting them can lose recovery evidence or reset spending/duplicate-submission safeguards. QA captures and historical session notes are not product source; archive them outside the repository when no longer needed.
Story & project credit budget
Only video generation uses credits — image generation and character creation cost 0 credits and bypass all credit caps/blocks. By default, every story and project allocates a 50-credit video budget (DEFAULT_STORY_BUDGET_CREDITS = 50). When planning a story (flow_script_create / flow_script_update), the MCP calculates estimatedRequiredCredits across all planned video shots (Veo Quality = 50, Veo Fast/Lite = 20, Omni Flash = 10 per take); if the story requires more than the allocated budget, the MCP asks you to approve a higher allocatedBudget before spending a single video credit (STORY_BUDGET_APPROVAL_REQUIRED). You can set projectCreditCap in config/flow.config.json to change the standalone fallback cap, or pass allocatedBudget directly on flow_script_create / flow_script_update. Optional max_credits adds a per-submission video ceiling; it does not raise the approved story budget. Quotes are reserved before clicking Generate on video submissions and remain reserved for uncertain/failed submissions to prevent accidental overspending. Restart the MCP after rebuilding (npm run build) to apply code changes.
License
This project is licensed under the MIT License.