convez.ai
MCP ServerAutomaçãoAvançado
Mitanshp5

Google Flow MCP

Mitanshp5/Google-Flow_MCP

Automação segura de imagem/vídeo via Google Flow sem compartilhar credenciais

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor 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_MCP

1 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

Estrelas
20
Forks
8
Acompanhando
0
Saúde
42%
Último commit
há 1 semana
Versão
—
Issues abertas
0
Contribuidores
3

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

  1. 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.
  2. The MCP server (src/index.js) connects to that Chrome instance via Playwright's connectOverCDP and drives the Google Flow web app — filling prompts, inspecting live credit quotes, observing network acknowledgements, and reading results.
  3. 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 returns ready_for_confirmation. Image and character generation are always free (0 credits) and are never blocked for credit reasons. Paid video credit spend requires explicit flow_generate_confirm (or confirm_generate: true) gated by max_credits, a 50-credit default story/project budget (calculates required story credits up front and prompts for explicit allocatedBudget approval 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 in security/account-cooldowns.json (1800s unusual activity, 900s CAPTCHA gate, 300s rate 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 observes batchexecute RPC traffic (ogiZ0b for images; eb1hJf, YhhmEf, nprQif, MZZa6b for video) to extract operationIds and mediaIds, cross-checked against independent Flow DOM verification. Never invokes private RPCs directly or performs blind retries on submission_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 engines in package.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.

  1. Open Chrome and go to chrome://version
  2. 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
  • macOS:
    • Executable: /Applications/Google Chrome.app/Contents/MacOS/Google Chrome (Auto-detected)
    • User Data: /Users/<username>/Library/Application Support/Google/Chrome
  • Linux:
    • Executable: /opt/google/chrome/chrome or /usr/bin/google-chrome (Auto-detected)
    • User Data: /home/<username>/.config/google-chrome

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:

  1. Open Cursor Settings > Features > MCP.
  2. Click + Add New MCP Server.
  3. Name: Google-Flow
  4. Type: command
  5. Command: node /absolute/path/to/Google-Flow_MCP/dist/index.js (run npm run build first; src/index.js works 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

  1. npm run start-browser — once per session, leave the Chrome window open (or reuse an already-open Chrome: flow_list_browser_targets finds its CDP port, flow_connect takes cdpPort)
  2. 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 in
    • flow_list_models — list live video/image models, ratios, durations (call once per session before generating; cache reports stale/cacheAgeMs)
    • flow_create_project — mint a brand-new project (never reuses/renames an existing one; pin it via project_url)
    • flow_generate_image — prepare (or with auto_confirm:true, generate) images in a Flow project
    • flow_create_character — create reusable characters (optional archetype starter card)
    • flow_generate_video — prepare (or with confirm_generate:true, paid-generate) videos, optionally referencing previously generated images/characters via ingredients (@name references)
    • flow_generate_confirm — live-click Generate for a verified ready_for_confirmation preparation (images/characters are 0 credits and never credit-blocked; video is gated by story allocatedBudget and max_credits: Omni ~10, Veo Fast/Lite ~20, Veo Quality ~50; never confirms prepared_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 with flow_script_create .. flow_script_resume using ROOT, CONTINUATION, and INSERT shot edges, 7 entity types (character, location, prop, visual_asset, creature, generic_troop, faction), automated CONTINUITY_BREAK validation, last-frame carry-forward (start_frame / end_frame), and sceneChains tracking in getStoryStatus.
  • Selective Prompt Scaffolding (subject, setting, audio, negative, include_standard_negative): flow_generate_image and flow_generate_video compose structured prompts in src/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_WEIGHTS summing to 1.00) via evaluateVideoReview() and generateAdvisoryFixGuide(). Output is strictly advisory (advisoryOnly: true, requiresAuthorizationForRegen: true).
  • Continuity-Safe FFmpeg Assembly (scripts/assemble-video.mjs): Standalone local FFmpeg script normalizing clips to H.264 yuv420p and 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 on CONTINUATION shots so frame-chained cuts remain seamless.

In an agent client with this repository available, ask:

Read skills/google-flow-production/SKILL.md and 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

ToolPurpose
flow_connectConnect to / launch Chrome via CDP, optionally open Flow (cdpPort reuses an already-open browser)
flow_disconnectClose the browser connection
flow_list_browser_targetsProbe local CDP ports for a listening Chrome (no browser needed)
flow_create_projectMint a brand-new project (never reuses/renames; pin via project_url)
flow_list_projectsList known projects from the local registry (no browser needed)
flow_openNavigate the connected browser to a Flow URL without reconnecting
flow_statusReport current connection/page status
flow_account_checkIdentify the signed-in Google account; enforce expectedAccount only if configured
flow_discover_uiNavigate to a Flow page and dump interactive elements (debugging)
flow_generate_imageGenerate image(s) from a prompt in the current project (free — 0 credits; prepare-only by default; auto_confirm:true submits immediately)
flow_generate_videoGenerate video(s), optionally with ingredients/use_character/use_scene references (prepare-only by default; confirm_generate:true spends credits)
flow_generate_confirmLive-click Generate for a verified ready_for_confirmation job, gated by max_credits (never confirms prepared_unverified)
flow_rename_characterRename a character in its detail page (never the project title)
flow_rename_imageRename an existing image by exact name or asset_id, with new_name and optional project scope
flow_list_modelsList video/image models, ratios, durations from Flow UI (live) or cache
flow_download_latestDownload an existing asset in the open project; returns choices when newest cannot be verified
flow_create_characterCreate a new character (name + description + optional archetype starter + reference images)
flow_import_characterImport a character from a saved JSON file
flow_open_charactersOpen the Characters page for a project
flow_list_mention_optionsList images/characters available for @name references
flow_open_tools_galleryOpen Flow's Tools gallery
flow_use_toolUse an arbitrary tool from the Tools gallery
flow_screenshotTake a debug screenshot of the current page
flow_queue_statusCheck the status of queued generation jobs
flow_queue_resetForcefully reset the job queue if a job is stuck in "running" state
flow_script_createCreate a structured script, continuity bible, DAG, and policy in immutable revision storage (zero credit spend)
flow_script_updateUpdate script brief, bible, scenes, or shots under CAS revision control and compute DAG invalidations
flow_script_statusQuery script continuity status, sceneChains, shot readiness, blocking prerequisites, and next steps
flow_script_reviewSubmit digest-bound human/director reviews, score candidates, or update reference/pack selections
flow_script_runStage bounded local image-candidate intents, local_import assets, or review-artifacts contact sheets
flow_script_resumeResume/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:

FieldDescriptionDefault
expectedAccountOptional email restriction; null accepts any positively identified signed-in accountnull
chromeExecutableFull path to chrome executable (optional, auto-detected)auto-detected
chromeUserDataDirPath to Chrome's "User Data" folderauto-detected per-OS
chromeProfileProfile folder name (e.g. Default, Profile 1)Default
cdpPortChrome DevTools Protocol port9222
flowUrlBase Google Flow URLhttps://flow.google.com/
headlessRun Chrome headless (not recommended — Flow needs visible browser)false
jobTimeoutMsWatchdog: max time a job may stay running before auto-fail300000
jobHistoryLimitBounded queue history kept in flow_queue_status50
actionDelayMsDelay between automated UI steps800
agentResponseTimeoutMs / generationTimeoutMsAgent dialog window / generation wait5000 / 120000
downloadWaitMsWait for download to complete30000
imageModels / videoModelsDisplay name → internal model ID maps (merged with live discovery)see example config
ratios / videoRatios / durations (4s,6s,8s,10s) / quantitiesAllowed generation parameterssee 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=AutomationControlled flag. 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 (0 credits) 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 requires confirm_generate: true). flow_create_character also defaults to false.
  • Account-level safety protections (unusual-activity / CAPTCHA / rate-limit circuit breaker) still apply uniformly to protect your Google account.
  • flow_disconnect never kills your personal Chrome tabs — it detaches unless the server launched Chrome itself.
  • flow_account_check is fail-closed: without positive evidence it returns verified:false, needsManualCheck:true (never assumed:true).
  • config/flow.config.json is 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 generated scripts/*/ 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.

Ver o original no GitHub

Bom para

Relacionados