Google Flow Browser MCP
Allows control of Google Flow (labs.google/fx/tools/flow) to generate images, videos, characters, and scenes using a logged-in Chrome profile.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Google Flow Browser MCP generate an image of a cat flying a kite"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Google Flow Browser MCP
An MCP (Model Context Protocol) server that lets an AI agent drive
Google Flow (labs.google/fx/tools/flow)
through your own logged-in Chrome profile — generating images, videos,
characters, and 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.
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, clicking buttons, reading results.Your AI agent (Claude / OpenCode / any MCP client) talks to the MCP server over stdio and calls tools like
flow_generate_image,flow_generate_video,flow_create_character, etc.
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.
Related MCP server: google-flow-mcp
Prerequisites
Node.js 18 or later (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/shaig-mahmudov/google-flow-mcp.git
cd google-flow-mcp
npm installnpm 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://versionLook 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/chromeor/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. To avoid conflicts and profile locking issues, we strongly recommend creating a dedicated Chrome profile specifically for this MCP server (e.g. named "GoogleFlowBot"), signing into your Google account there once, and configuring the server to use it. If you attempt to run the server while actively browsing with the same profile, the connection may fail.
3. Create your config file
Copy the example config and edit it:
Windows (PowerShell):
copy config\flow.config.example.json config\flow.config.jsonmacOS / Linux:
cp config/flow.config.example.json config/flow.config.jsonOpen config/flow.config.json and set at minimum:
{
"expectedAccount": "your-email@gmail.com",
"chromeProfile": "Profile 1"
}(Replace "Profile 1" with the actual folder name of your dedicated GoogleFlowBot profile, which you can find in chrome://version)
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-browserThis 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-mcpThis 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 registerThis 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:
{
"mcpServers": {
"Google-Flow": {
"command": "node",
"args": ["/absolute/path/to/google-flow-mcp/src/index.js"]
}
}
}Antigravity Currently, Antigravity requires manual configuration: Add the following to your Antigravity MCP config:
{
"mcpServers": {
"google-flow": {
"command": "node",
"args": [
"C:/{path}/src/index.js"
]
}
}
}(Replace C:/{path}/ with the actual path to the project directory)
Cursor (Codex) Currently, Cursor requires manual UI configuration:
Open Cursor Settings > Features > MCP.
Click + Add New MCP Server.
Name:
Google-FlowType:
commandCommand:
node /absolute/path/to/google-flow-mcp/src/index.js
4. Verify everything end-to-end
With Chrome running (step 1), run:
npm run testThis sends a flow_connect tool call to the MCP server over stdio and prints the raw response.
You can also run the Node-based end-to-end test suite:
node scripts/test-e2e.mjsTypical workflow
npm run start-browser— once per session, leave the Chrome window openYour AI agent (with this MCP registered) calls:
flow_connect— attach to the running Chromeflow_account_check— confirm the right Google account is signed inflow_generate_image— create images in a Flow projectflow_create_character— create reusable charactersflow_generate_video— create videos, optionally referencing previously generated images/characters viaingredients(@namereferences)flow_list_mention_options— see what images/characters are available to reference by nameflow_create_scene— create a new scene, optionally referencing characters
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.
Available tools
Tool | Purpose |
| Connect to / launch Chrome via CDP, optionally open Flow |
| Close the browser connection |
| Report current connection/page status |
| Verify the signed-in Google account matches |
| Navigate to a Flow page and dump interactive elements (debugging) |
| Generate image(s) from a prompt in the current project |
| Generate video(s), optionally with |
| Download the most recently generated asset |
| Create a new character (name + description + reference images) |
| Import a character from a saved JSON file |
| Open the Characters page for a project |
| List images/characters available for |
| Create a new scene, optionally referencing characters |
| Open Flow's Tools gallery |
| Open the Grid Architect tool |
| Use an arbitrary tool from the Tools gallery |
| Take a debug screenshot of the current page |
| Check the status of queued generation jobs |
Configuration reference
All settings live in config/flow.config.json (copy from flow.config.example.json). Key fields:
Field | Description | Default |
| Google account email | (required) |
| Full path to | auto-detected |
| Path to Chrome's "User Data" folder | auto-detected |
| Profile folder name (e.g. |
|
| Chrome DevTools Protocol port |
|
| Base Google Flow URL |
|
| Run Chrome headless |
|
| Max time to wait for a generation job |
|
| Display name → internal model ID maps | see example config |
| Allowed generation parameters | see example config |
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.
Project layout
config/
flow.config.example.json # template — copy to flow.config.json
selectors.map.json # auto-updated cache from flow_discover_ui
scripts/
run.js # OS-independent command dispatcher
start-browser.ps1 / .sh # launch Chrome with CDP debugging
start-mcp.ps1 / .sh # run the MCP server (manual check)
register-opencode.ps1 / .sh# register this server with OpenCode
test-flow-image.ps1 / .sh # quick flow_connect smoke test
test-e2e.mjs # multi-tool Node end-to-end test
src/
index.js # MCP server entry point
browser/ # Chrome/CDP connection logic
navigation/ # project navigation, @ mention references
tools/ # one file per MCP tool
utils/ # config, logging, screenshots, file outputSafety notes
This server only automates a browser you already control and are signed into — it does not store, transmit, or need your Google credentials.
Image and video generation consume Google Flow credits. Generation tools default to safe "prepare only" behavior (
auto_confirm: false).config/flow.config.jsonis gitignored — do not commit it.
License
This project is licensed under the MIT License.
Available Tools
19 toolsflow_account_checkA
Verify the logged-in Google account matches the configured expected email (Default).
Inputs: no named parameters.
flow_connectA
Launch Chrome with the configured Google profile, connect CDP, navigate to Google Flow, and verify account.
Inputs: headless, open_flow.
flow_create_characterA
Create a new character in Google Flow Characters with name and description. By default (auto_confirm not false), fills the description and clicks the submit arrow to actually create the character, then renames "Untitled Character" to the given name.
Inputs: name (required), description (required), campaign, auto_confirm, +2 more.
flow_create_sceneB
Create a new scene in Google Flow Scenes with characters and prompt.
Inputs: prompt (required), campaign, characters, project_name.
flow_disconnectA
Close the browser and clean up the MCP connection to Google Flow.
Inputs: no named parameters.
flow_discover_uiA
Navigate to a Google Flow page and discover all interactive elements (buttons, inputs, links, headings). Updates the internal selectors map for robust automation.
Inputs: page (required), url, campaign, project_name.
flow_download_latestB
Download the most recently generated file from Google Flow.
Inputs: no named parameters.
flow_generate_imageA
⚠️ THESE IMAGES CONSUME CREDITS. By default (auto_confirm=false): fills the prompt, selects model/ratio, takes a screenshot and returns "ready_for_confirmation". Does NOT click Generate. When auto_confirm=true: first verifies the UI is in IMAGE mode (not Video), that the model is an image model, takes a verification screenshot, THEN clicks Generate and waits for the images. NANO/BANANA image models only.
Inputs: prompt (required), brand, model, ratio, +6 more.
flow_generate_videoA
Set up a video generation in Google Flow. Fills prompt, selects Omni Flash or Veo model, configures settings. NOTE: Does NOT click final Generate (paid feature — stops at ready-to-generate).
Inputs: prompt (required), model, ratio, campaign, +6 more.
flow_import_characterA
Import a character from a saved JSON file into Google Flow.
Inputs: file_path (required), campaign, project_name.
flow_list_mention_optionsA
List the images and characters in the current project that can be referenced via "@name" in an image/video prompt (opens Flow's "@" reference popup and reads its options).
Inputs: campaign, project_name.
flow_open_charactersB
Open the Characters page for the current/target project and list existing characters.
Inputs: campaign, project_name.
flow_open_tools_galleryA
Open the Google Flow Tools Gallery and list available tools.
Inputs: no named parameters.
flow_queue_resetA
Forcefully reset the job queue. Use this if a job is permanently stuck in "running" state and blocking other generations.
Inputs: no named parameters.
flow_queue_statusA
Check the job queue: active job, pending queue, completed and failed job history.
Inputs: history_limit.
flow_screenshotB
Take a screenshot of the current Google Flow page.
Inputs: name.
flow_statusB
Check current connection status: browser connected, Flow page loaded, account verified, job queue state.
Inputs: full.
flow_use_grid_architectA
Open Grid Architect in Google Flow, fill theme prompt, shot prompts, engine, ratio, and visual logic settings. Supports batch shot generation for brand campaigns.
Inputs: theme_prompt (required), ratio, engine, campaign, +4 more.
flow_use_toolB
Open any tool by name in Google Flow and optionally fill its configuration parameters.
Inputs: tool_name (required), params, campaign, project_name.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 19 tools
Tools are mostly distinct, covering connection, generation, characters, scenes, queue, and UI automation. Minor overlap exists between flow_status and flow_queue_status (both report queue state), and flow_use_tool vs flow_use_grid_architect (specialized case), but descriptions and parameters generally disambiguate clearly.
All tools share the 'flow_' prefix and use snake_case, with a predominantly verb-noun pattern (e.g., flow_generate_image, flow_create_character). A few object-led names like flow_account_check, flow_queue_status, and flow_queue_reset deviate from the verb-first convention, but the overall pattern remains readable and predictable.
With 19 tools, this is on the heavier side but justified by the broad scope of Google Flow automation: connection, media generation, character/scene management, queue control, and UI discovery. The count feels appropriate for the range of capabilities, though it approaches the threshold where complexity can become unwieldy.
Core workflows are covered, but there are notable gaps: no update/delete for characters or scenes, no list-scenes tool (while list-characters exists), and video generation stops short of triggering the final generation, leaving a dead end. Generic flow_use_tool and flow_discover_ui offer workarounds, but the surface is not fully self-sufficient for entity lifecycle management.
Maintenance
Related MCP Connectors
Let AI agents use your real, signed-in Chrome: tabs, clicks, forms, screenshots and video.
Connect AI agents to your own Chrome with scoped access, approvals, and verified task results.
Let AI agents use any website you're logged in to. Sessions stay encrypted on your machine.
Give AI agents a real cloud Chrome: open sessions, navigate, read pages, click, type and screenshot.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables AI agents to programmatically generate images and videos through the authenticated Google Flow web interface via a direct Chrome DevTools Protocol connection, exposing tools for media generation, project management, status checks, and asset downloads without requiring official API keys.276MIT
- AlicenseAqualityBmaintenanceEnables AI agents to generate Google Flow videos and images and automate Scene Builder clip extensions through a user's own Chrome session.11264 npm10MIT
- AlicenseNot gradedqualityCmaintenanceEnables generating images and videos in Google Flow through an automated browser session using your Google AI Pro subscription, without API keys or third-party credit fees.117 npm2MIT
- AlicenseAqualityBmaintenanceLets an AI agent drive Google Flow (flow.google.com) through a locally logged-in Chrome profile to generate images, videos, characters, and scenes. Uses browser automation via the Chrome DevTools Protocol, so Google credentials are never shared with the agent.2110 npmMIT