google-flow-mcp
Provides programmatic access to Google Flow, enabling AI agents to generate images with Nano Banana 2/Pro and videos with Veo 3, as well as manage projects and retrieve credit and session information.
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-mcp Generate an image of a cozy cabin in snowy woods at dusk with warm lights, 16:9"
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 MCP Server
A session-backed, direct-CDP UI-to-MCP wrapper for Google Flow (labs.google/fx/tools/flow), implementing the Browser as an API paradigm to provide programmatic access to Nano Banana 2/Pro image generation and Veo 3 video generation models.
Disclaimer: This project is an unofficial, independent open-source tool and is not affiliated with, endorsed by, or associated with Google or Google Labs. Use this software at your own risk. The authors and contributors assume no liability or responsibility for any account suspension, service restriction, credit consumption, or terms-of-service enforcement resulting from the use of this software. Users are solely responsible for complying with Google's Terms of Service and applicable policies.
Overview
This server acts as a UI-to-API bridge, enabling AI agents (Claude Desktop, Cursor, Windsurf, Cline, Antigravity, etc.) to control Google Flow using structured JSON-RPC over standard I/O. By attaching directly to an existing Chrome debugging session over WebSocket, it bypasses the need for official API keys, handles bot detection transparently via real user session context, and achieves sub-25ms execution latency with in-page binary streaming and live credit telemetry.
Related MCP server: Google Flow MCP
Features
Browser as an API: Treats the authenticated Google Flow web interface as a programmable, queryable tool for AI agents.
Session-Backed CDP Engine: Connects directly over raw WebSocket to a persistent Chrome debugging profile, preserving Google OAuth session state and avoiding bot-detection challenges.
Multi-Reference Injection: Attaches canonical character and background reference images directly into the prompt bar as input chips.
In-Page Binary Streaming: Retrieves generated high-resolution assets via authenticated in-page
fetch()without page reloads.Standardized MCP Interface: Exposes Tools, Resources (
flow://credits,flow://session,flow://projects), and Prompt Templates.Cross-Platform Binary Discovery: Automatically locates Chrome, Brave, Chromium, or Edge installations across macOS, Windows, and Linux.
Multi-Language UI Support: Employs semantic SVG icon matching and multilingual fallback dictionaries (KO, EN, JA, FR, ES).
Prerequisites
Node.js >= 18.0.0
Google Chrome, Brave, Chromium, or Microsoft Edge
An active Google account with access to Google Flow (
https://labs.google/fx/tools/flow)
Installation Options
Option 1: Automatic Setup via AI Agent (Recommended)
Copy and paste the following prompt directly into your AI coding assistant (Cursor, Claude Code, Windsurf, Antigravity, Cline, etc.):
Please install and configure the google-flow-mcp server for my current environment:
1. Clone https://github.com/vynnlee/google-flow-mcp to an appropriate local directory and run `npm install`.
2. Locate the MCP configuration file for my current client (e.g., Claude Desktop, Cursor `.cursor/mcp.json`, Windsurf, Cline) and add the "google-flow" server entry pointing to the cloned `src/index.js`.
3. Run `npm run launch` to open the dedicated Chrome profile so I can log in to Google Flow.
4. Verify the setup by running `npm run test:e2e` and confirm that all tests pass.Option 2: MCPB Bundle (.mcpb) Drag & Drop
Download the pre-packaged google-flow-mcp-1.2.0.mcpb bundle from the Releases page and drag it directly into your MCP-compatible client interface.
Option 3: Manual Installation (3 Steps)
1. Clone and Install Dependencies
git clone https://github.com/vynnlee/google-flow-mcp.git
cd google-flow-mcp
npm install2. Launch Dedicated Browser Profile
Run the cross-platform launcher to start your persistent automation browser:
npm run launchLog in to your Google account once in the opened window. Your authentication is preserved across restarts in a dedicated user data directory.
(Manual alternative: launch Chrome with --remote-debugging-port=9333 and --user-data-dir="<path>")
3. Add to Your AI Client
Add the following standard MCP configuration to your AI client's settings:
{
"mcpServers": {
"google-flow": {
"command": "node",
"args": [
"/absolute/path/to/google-flow-mcp/src/index.js"
]
}
}
}Settings File Locations
Client | Configuration File Path |
Claude Desktop |
|
Cursor |
|
Windsurf |
|
Cline / Roo Code |
|
Zed |
|
Optional Configuration
Create config/flow.config.json to override default parameters:
{
"cdpPort": 9333,
"expectedAccount": "your-email@gmail.com",
"defaultImageModel": "Nano Banana 2",
"defaultRatio": "16:9",
"autoConfirm": false
}Components
Tools
flow_generate_image
Generates images using Nano Banana 2, Nano Banana Pro, or Imagen 4 with optional reference image attachment.
Parameters:
prompt(string, required): Detailed prompt describing the scene, subject, camera angle, and style.reference_images(string[], optional): Absolute file paths to reference images to inject as prompt chips.model(string, optional):"Nano Banana 2"(default),"Nano Banana Pro", or"Imagen 4".ratio(string, optional):"16:9"(default),"9:16","1:1","4:3", or"3:4".auto_confirm(boolean, optional): Set totrueto execute generation and consume credits. Iffalse, prepares the prompt in the UI without generating. Default:false.output_folder(string, optional): Directory path where downloaded files are saved.response_format(string, optional):"detailed"(default) or"concise".
flow_generate_video
Generates video clips using Veo 3.1 or Omni Flash.
Parameters:
prompt(string, required): Prompt describing camera movement and motion.model(string, optional):"Veo 3.1 Lite"(default),"Veo 3.1 Quality", or"Omni Flash".duration(string, optional):"4s","6s"(default), or"8s".ratio(string, optional):"16:9"(default),"9:16", or"1:1".auto_confirm(boolean, optional): Default:false.output_folder(string, optional): Destination directory path.response_format(string, optional):"detailed"(default) or"concise".
flow_status
Returns browser connection health, current account state, session validity, and real-time credit balance.
Parameters:
full(boolean, optional): Include complete telemetry payload. Default:true.
flow_manage_project
Lists or creates projects on the Flow canvas.
Parameters:
action(string, required):"list"or"create".name(string, optional): Required when action is"create".
flow_download_latest
Downloads the most recently rendered asset without triggering new generation.
Parameters:
output_folder(string, optional): Destination directory.
flow_connect / flow_disconnect
Manages the connection state to the dedicated Chrome browser instance.
Resources
flow://credits: Returns real-time JSON payload containing remaining credit balance, subscription tier, and SKU.flow://session: Returns authenticated user profile, email address, and OAuth expiration timestamp.flow://projects: Returns array of active projects on the user's canvas.
Prompts
consistent-storyboard-cut: Parameterized template for generating camera-consistent scene cuts with character and environment references.
Architecture
flowchart TD
Client["AI Clients and IDEs\n(Claude Desktop, Cursor, Windsurf, Cline)"]
subgraph MCPServer["google-flow-mcp (Node.js Server)"]
Router["Tool & Resource Router\n(Tools, Resources, Prompts)"]
Engine["Direct CDP WebSocket Engine\n(~21ms Low-Latency Control)"]
MultiRef["Multi-Reference Chip Injector\n(Characters & Backgrounds)"]
StreamFetch["In-Page Binary Stream Fetcher\n(Direct Asset Retrieval)"]
end
subgraph Browser["Dedicated Chrome Instance (:9333)"]
Session["Persistent Google OAuth Session\n(FlowAutomationChrome Profile)"]
Flow["Google Flow WebApp\n(Nano Banana 2/Pro & Veo 3)"]
end
Client -->|Stdio JSON-RPC| Router
Router --> MultiRef --> Engine
Engine -->|Raw WebSocket CDP| Session
Session --> Flow
Flow -.->|Authenticated Media Stream| StreamFetch
StreamFetch -.->|JPG / MP4 Assets + Credits JSON| ClientPerformance Benchmark
Measured on macOS against Google Chrome remote debugging port 9333 (5-run mean):
Metric | Standard Automation (Playwright CDP) | Direct CDP WebSocket Engine | Delta |
Initial Handshake | 354.25 ms | 21.80 ms | 16.2x faster |
DOM Traversal / Query | 21.29 ms | 1.65 ms | 12.9x faster |
Screenshot Capture | 383.92 ms | 359.95 ms | 6.2% faster |
Single Transaction Runtime | 761.31 ms | 384.17 ms | 1.98x faster |
Process Memory (RSS) | 166.81 MB | 52.31 MB | 68.6% reduction |
Troubleshooting & FAQ
Browser Connection Failed
Ensure the browser is running with
--remote-debugging-port=9333. You can verify by openinghttp://localhost:9333/jsonin your browser.If port 9333 is occupied by another process, change
cdpPortinconfig/flow.config.json.
Re-Authentication Required
If Google Flow displays a login prompt, open the dedicated Chrome window, log in with your Google account, and refresh the page. The session will remain active.
Using Custom Browser Paths
Set the
CHROME_PATHenvironment variable to point to your specific browser binary (e.g., Brave or Edge):export CHROME_PATH="/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"
Development & Testing
Run unit and connection tests:
npm testRun full MCP specification compliance audit:
npm run test:e2eDebug using MCP Inspector:
npx @modelcontextprotocol/inspector node src/index.jsLicense
MIT License. Copyright (c) 2026 Vynn Lee.
Available Tools
7 toolsflow_connectB
Establishes connection to Google Flow Chrome instance on CDP port (default: 9333).
Inputs: headless.
flow_disconnectA
Closes the browser connection and cleans up MCP state.
Inputs: no named parameters.
flow_download_latestB
Downloads the most recently rendered image or video asset from the active Flow project without re-generating.
Inputs: output_folder.
flow_generate_imageA
Generates high-fidelity images on Google Flow using Nano Banana 2, Nano Banana Pro, or Imagen 4. Supports attaching multiple reference images (e.g. character sheet + background environment) as prompt attachment chips. When auto_confirm=true, submits the prompt and downloads high-res images to output_folder. When auto_confirm=false (default), prepares the prompt and references in the UI for safety review without consuming credits.
Inputs: prompt (required), model, ratio, auto_confirm, +3 more.
flow_generate_videoA
Generates cinematic video clips on Google Flow using Veo 3.1 or Omni Flash. When auto_confirm=true, submits generation, monitors rendering progress, and downloads the MP4 file. When auto_confirm=false, prepares prompt without consuming credits.
Inputs: prompt (required), model, ratio, duration, +3 more.
flow_manage_projectB
Lists existing Flow projects or creates a new project on the user canvas.
Inputs: action (required), name.
flow_statusA
Checks the health and telemetry of Google Flow: Chrome CDP connection state, active user account, session expiration, and real-time remaining credit balance.
Inputs: full.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool targets a distinct concern: connection lifecycle, status, project management, image generation, video generation, and asset download. There is no meaningful overlap or ambiguity between them.
All tools follow the same flow_verb_noun pattern with snake_case, making the set predictable and easy to navigate. Even the less specific flow_manage_project fits the established convention.
Seven tools is well-scoped for a Google Flow MCP server, covering connection, status, project management, generation, and download without unnecessary duplication. Each tool earns its place.
The core workflow is covered: connect, manage projects, generate images/videos, and download results. Minor gaps exist such as no way to fetch a specific historical asset or cancel an in-progress generation, but these are not fatal to the primary use case.
Maintenance
Related MCP Connectors
Google Flow's agent: chat that plans and makes images and videos, approvals, your own media
Build and run visual creative-production workflows from your AI agent.
Give AI agents a real cloud Chrome: open sessions, navigate, read pages, click, type and screenshot.
Cloud browser, web extraction, screenshots, and remote CDP tools for AI agents.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI agents to drive Google Flow through a real Chrome profile to generate images, videos, characters, and scenes without sharing credentials.192MIT
- AlicenseBqualityBmaintenanceEnables users to generate images and videos on Google Flow through browser automation of an already signed-in Chrome session, downloading the finished media to disk without any API keys. It drives Flow's agent with a range of image and video models, plus reference images, first/last frames, and ingredient-based video jobs, while reusing the user's own Google AI Pro credits.17MIT
- 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
- AlicenseBqualityBmaintenanceEnables generating images and videos on Google Flow through browser automation using an authenticated Chrome session, with tools to connect, generate, download media, and manage characters and scenes.17MIT