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.

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: Chrome DevTools 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 install

2. Launch Dedicated Browser Profile

Run the cross-platform launcher to start your persistent automation browser:

npm run launch

Log 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

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 to true to execute generation and consume credits. If false, 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| Client

Performance Benchmark

Measured on macOS against Google Chrome remote debugging port 9333 (5-run mean):

Troubleshooting & FAQ

Browser Connection Failed

• Ensure the browser is running with --remote-debugging-port=9333. You can verify by opening http://localhost:9333/json in your browser.

• If port 9333 is occupied by another process, change cdpPort in config/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_PATH environment 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 test

Run full MCP specification compliance audit:

npm run test:e2e

Debug using MCP Inspector:

npx @modelcontextprotocol/inspector node src/index.js

License

MIT License. Copyright (c) 2026 Vynn Lee.