Skip to main content
Glama

🧠 Google Flow Browser MCP

Control Google Flow β€” image & video generation β€” directly from your AI agent via MCP.

✨ Features β€’ πŸš€ Quick Start β€’ πŸ”§ Tools β€’ βš™οΈ Configuration β€’ πŸ›‘οΈ Safety


πŸ‡«πŸ‡· Ce serveur MCP permet Γ  votre agent AI (OpenCode) d'utiliser Google Flow pour gΓ©nΓ©rer des images et des vidΓ©os, via votre propre compte Google et sans partager vos identifiants.


πŸ“Έ What It Does

This MCP server connects your AI agent to Google Flow β€” Google's creative suite for image and video generation. Your agent can:

  • 🎨 Generate images with Nano Banana Pro, Nano Banana 2, or Imagen 4

  • 🎬 Create videos and scenes with characters

  • πŸ§‘ Manage characters and scenes in your Flow workspace

  • πŸ–ΌοΈ Use Grid Architect for batch shot generation

  • πŸ” Discover and control any Flow tool programmatically

All through your own Google account β€” no API keys, no third-party tokens.


Related MCP server: google-flow-mcp

✨ Features

🎯 For AI Agents

πŸ”’ For Humans

  • 15+ MCP tools ready to use

  • Smart job queue β€” no parallel conflicts

  • Auto-discover UI β€” adapts to Flow changes

  • Structured logging for debugging

  • Safe actions β€” resilient click/fill logic

  • Your account, your data β€” no token sharing

  • No password asked β€” ever

  • Clean safety rules β€” stops on captcha/verification

  • Config backup before any modification

  • Single-job queue β€” no runaway generation


πŸš€ Quick Start

Prerequisites

What

Why

Node.js β‰₯ 18

Runtime for the MCP server

Google Chrome

Required for browser automation

OpenCode

AI agent that connects to MCP servers

A Google account

To use Google Flow (yours, not shared)

1️⃣ Install

git clone https://github.com/TMSSS05/google-flow-browser-mcp.git
cd google-flow-browser-mcp
npm install

2️⃣ Configure your Google profile

cp config/flow.config.example.json config/flow.config.json

Edit config/flow.config.json:

{
  "expectedAccount": "your.email@gmail.com",
  "chromeProfile": "Profile 3",
  "chromeUserDataDir": "/home/you/.config/google-chrome"
}

πŸ’‘ Finding your Chrome profile:
Open Chrome and go to chrome://version/. Look for "Profile Path" β€” the last folder name is your profile (e.g., Profile 3), and the path before it is your chromeUserDataDir.

3️⃣ Make scripts executable

chmod +x scripts/*.sh

4️⃣ Start Chrome with CDP

./scripts/start-browser.sh

This launches Chrome with remote debugging enabled on port 9222 using your configured profile.

5️⃣ Start the MCP server

# In a separate terminal:
./scripts/start-mcp.sh

6️⃣ Register with OpenCode

./scripts/register-opencode.sh

πŸ”„ Restart OpenCode after registration for the changes to take effect.

βœ… Verify it works

./scripts/test-flow-image.sh

πŸ—οΈ Architecture

google-flow-browser-mcp/
β”‚
β”œβ”€β”€ πŸ“‚ config/
β”‚   β”œβ”€β”€ flow.config.example.json    # Configuration template
β”‚   └── selectors.map.json          # UI selectors (auto-populated)
β”‚
β”œβ”€β”€ πŸ“‚ scripts/
β”‚   β”œβ”€β”€ start-browser.sh            # Launch Chrome + CDP
β”‚   β”œβ”€β”€ start-mcp.sh                # Start the MCP server
β”‚   β”œβ”€β”€ test-flow-image.sh          # Quick integration test
β”‚   └── register-opencode.sh        # Register in OpenCode config
β”‚
β”œβ”€β”€ πŸ“‚ src/
β”‚   β”œβ”€β”€ index.js                    # MCP server entry point
β”‚   β”‚
β”‚   β”œβ”€β”€ πŸ“ browser/                 # Chrome & CDP management
β”‚   β”‚   β”œβ”€β”€ connect.js              # CDP connection manager
β”‚   β”‚   β”œβ”€β”€ launch-profile.js       # Chrome profile launcher
β”‚   β”‚   β”œβ”€β”€ account-check.js        # Verify Google account
β”‚   β”‚   └── safe-actions.js         # Safe click, fill, detection
β”‚   β”‚
β”‚   β”œβ”€β”€ πŸ“ tools/                   # All MCP tool implementations
β”‚   β”‚   β”œβ”€β”€ flow-open.js            # Navigate to Flow
β”‚   β”‚   β”œβ”€β”€ flow-status.js          # Connection status
β”‚   β”‚   β”œβ”€β”€ generate-image.js       # Image generation
β”‚   β”‚   β”œβ”€β”€ generate-video.js       # Video generation (setup only)
β”‚   β”‚   β”œβ”€β”€ download-latest.js      # Download generated files
β”‚   β”‚   β”œβ”€β”€ create-character.js     # Create a character
β”‚   β”‚   β”œβ”€β”€ import-character.js     # Import character JSON
β”‚   β”‚   β”œβ”€β”€ open-characters.js      # List characters
β”‚   β”‚   β”œβ”€β”€ create-scene.js         # Create a scene
β”‚   β”‚   β”œβ”€β”€ open-tools-gallery.js   # Open tools gallery
β”‚   β”‚   β”œβ”€β”€ grid-architect.js       # Batch shot generation
β”‚   β”‚   β”œβ”€β”€ discover-ui.js          # UI discovery & mapping
β”‚   β”‚   └── use-flow-tool.js        # Generic tool opener
β”‚   β”‚
β”‚   β”œβ”€β”€ πŸ“ queue/                   # Job management
β”‚   β”‚   └── job-queue.js            # Single-job queue
β”‚   β”‚
β”‚   └── πŸ“ utils/                   # Helpers
β”‚       β”œβ”€β”€ config.js               # Config loader
β”‚       β”œβ”€β”€ logger.js               # Structured logging
β”‚       β”œβ”€β”€ errors.js               # Error codes & types
β”‚       β”œβ”€β”€ file-manager.js         # File download/save
β”‚       └── screenshots.js          # Screenshot capture
β”‚
└── πŸ“‚ output/                      # Generated files land here

πŸ”§ Tools

All tools are organized by function for easy discovery.

🌐 Connection & Status

Tool

Description

flow_connect

Launch Chrome, connect CDP, navigate to Google Flow

flow_disconnect

Close browser and clean up all connections

flow_status

Full status: connection, Flow loaded, account, queue state

flow_account_check

Verify logged-in account matches configured email

flow_screenshot

Capture a screenshot of the current Flow page

🎨 Image Generation

Tool

Description

flow_generate_image

Generate image with Nano Banana Pro, Nano Banana 2, or Imagen 4. Supports aspect ratios, reference images, and brand-based model selection.

flow_download_latest

Download the most recently generated file

🎬 Video Generation

Tool

Description

flow_generate_video

Set up video generation (Omni Flash, Veo models, custom duration/ratio). ⚠️ Stops at "ready to generate" β€” no credit consumed.

flow_create_scene

Create a video scene with characters and a text prompt

πŸ‘€ Characters

Tool

Description

flow_create_character

Create a new character with name, description, and optional reference images

flow_import_character

Import a character from a saved JSON file

flow_open_characters

Open the characters page and list all existing characters

πŸ› οΈ Tools & Discovery

Tool

Description

flow_open_tools_gallery

Open the tools gallery and browse available tools

flow_use_tool

Open any Flow tool by name with optional parameters

flow_use_grid_architect

Configure Grid Architect for batch shot generation with theme prompts, visual logic, and reference images

flow_discover_ui

Discover and map all interactive elements (buttons, inputs, headings) on any Flow page

πŸ“Š Queue & Monitoring

Tool

Description

flow_queue_status

Check job queue: active job, pending queue, completed and failed history


βš™οΈ Configuration

Edit config/flow.config.json (copy from config/flow.config.example.json):

πŸ”‘ Essential

Key

Type

Default

Description

expectedAccount

string

β€”

Your Google account email βœ… REQUIRED

chromeProfile

string

"Profile 3"

Chrome profile directory name

chromeUserDataDir

string

β€”

Full path to Chrome user data directory βœ… REQUIRED

flowUrl

string

Flow labs URL

Google Flow URL (supports fr, en locales)

πŸ”§ Advanced

Key

Type

Default

Description

cdpPort

number

9222

Chrome DevTools Protocol port

browserMode

string

"direct-cdp"

"direct-cdp" (recommended) or "playwright"

headless

boolean

true

Run Chrome in headless mode

locale

string

"fr"

UI locale ("fr", "en", etc.)

⏱️ Timing

Key

Default

Description

jobTimeoutMs

300000 (5 min)

Max job execution time

actionDelayMs

800

Delay between UI actions (anti-detection)

generationPollIntervalMs

5000 (5s)

How often to poll for generation completion

maxPollAttempts

120

Max polling attempts before timeout

downloadWaitMs

30000 (30s)

Wait time for file download

🎨 Models & Ratios

Key

Description

imageModels

Available models: Nano Banana Pro, Nano Banana 2, Imagen 4

videoModels

Available models: Omni Flash, Veo 3.1 - Lite/Fast/Quality

ratios

Supported aspect ratios: 16:9, 4:3, 1:1, 3:4, 9:16


πŸ›‘οΈ Safety & Ethics

This project is built with safety-first design:

βœ… Principle

How it's enforced

Your account only

Uses your own Google profile β€” never asks for or stores passwords

No credential theft

Never exports cookies, tokens, or session data

No bypass

Stops cleanly on captcha, login walls, or verification challenges

No parallel abuse

Single-job queue prevents concurrent generation

Credit-safe video

Video generation sets up parameters but stops before the final "Generate" click (no credit consumed)

Config backup

Backs up OpenCode config before any modification

⚠️ This is a browser automation tool. Use it responsibly and in accordance with Google's Terms of Service.


❓ FAQ

Getting Started

Open Chrome and go to chrome://version/. The Profile Path shows both your user data directory and profile name. For example:

  • /home/you/.config/google-chrome/Profile 3 β†’ chromeUserDataDir: "/home/you/.config/google-chrome", chromeProfile: "Profile 3"

You need a profile where you're already logged into your Google account.

Yes! Any MCP-compatible client (Claude Desktop, Continue.dev, etc.) can connect to this server. Just point your MCP config to node /path/to/src/index.js.

Troubleshooting

Make sure Chrome is installed at the expected path. On Linux, the default is /opt/google/chrome/chrome. Edit scripts/start-browser.sh to set the correct CHROME path for your system.

The script checks for existing Chrome instances on port 9222. If something else is using that port, you can change cdpPort in config/flow.config.json (and update the script's CDP_PORT variable).

Verify that expectedAccount in config/flow.config.json matches the email logged into your Chrome profile. Use flow_account_check to verify.

Run flow_discover_ui to re-map selectors. The selectors.map.json will auto-update with new UI element positions.

Usage

Your AI agent calls flow_generate_image with a text prompt. Optionally specify model (Nano Banana 2 is default), aspect ratio, and reference images. The server waits for completion and makes the file available for download.

flow_generate_video sets up the video parameters (model, ratio, duration) but stops before clicking Generate. This lets you review the setup before consuming credits. The actual generation requires a paid Google Flow subscription.


🀝 Contributing

Contributions are welcome! Please follow these guidelines:

  1. Fork the repository

  2. Create a feature branch (git checkout -b feature/my-feature)

  3. Commit your changes (git commit -m 'Add my feature')

  4. Push to the branch (git push origin feature/my-feature)

  5. Open a Pull Request


πŸ“„ License

MIT Β© TMSSS05


Available Tools

17 tools
flow_account_checkA

Verify the logged-in Google account matches the configured expected email (Profile 3).

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_characterC

Create a new character in Google Flow Characters with name and description.

Inputs: name (required), description (required), reference_images, project_name, +1 more.

flow_create_sceneB

Create a new scene in Google Flow Scenes with characters and prompt.

Inputs: prompt (required), characters, project_name, campaign.

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).

flow_download_latestB

Download the most recently generated file from Google Flow.

Inputs: no named parameters.

flow_generate_imageA

⚠️ CES IMAGES CONSOMMENT DES CRΓ‰DITS. Par dΓ©faut (auto_confirm=false): remplit le prompt, sΓ©lectionne le modΓ¨le/ratio, prend un screenshot et retourne "ready_for_confirmation". NE clique PAS sur Generate. Quand auto_confirm=true: vΓ©rifie d'abord que l'interface est bien en mode IMAGE (pas VidΓ©o), que le modΓ¨le est un modΓ¨le image, prend un screenshot de vΓ©rification, PUIS clique Generate, attend les images et les tΓ©lΓ©charge. NAN/BANANA modΓ¨les image seulement.

Inputs: prompt (required), model, auto_confirm, ratio, +4 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, duration, +3 more.

flow_import_characterB

Import a character from a saved JSON file into Google Flow.

Inputs: file_path (required).

flow_open_charactersA

Open the Google Flow Characters page and list existing characters.

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), shot_prompts, engine, ratio, +4 more.

flow_use_toolA

Open any tool by name in Google Flow and optionally fill its configuration parameters.

Inputs: tool_name (required), params, project_name, campaign.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 17 tools

    Disambiguation4/5

    Most tools have distinct purposes (connection, character/scene management, generation, UI), but flow_generate_image and flow_generate_video could be confused if descriptions are skimmed. flow_use_tool is generic but still differentiated.

    Naming Consistency5/5

    All tools follow a strict 'flow_verb_noun' pattern with snake_case, e.g., flow_create_character, flow_generate_image. Naming is highly consistent and predictable.

    Tool Count4/5

    17 tools is appropriate for the scope of browser automation over Google Flow, covering connection, state management, content creation, and generation. Slightly on the higher side but well-justified.

    Completeness3/5

    Core CRUD for characters (create, import, list) but missing update/delete. No tools for scene management beyond creation. Video generation stops before final action, leaving a gap. UI discovery and queue status are nice extras.

    Maintenance

    ActivityInactive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers