<div align="center">

🧠 Google Flow Browser MCP

Control Google Flow — image & video generation — directly from your AI agent via MCP.

<p> <img src="https://img.shields.io/badge/version-1.1.0-blue?style=flat-square" alt="Version 1.1.0"> <img src="https://img.shields.io/badge/node-%3E%3D18-green?style=flat-square" alt="Node >= 18"> <img src="https://img.shields.io/badge/license-MIT-lightgrey?style=flat-square" alt="License MIT"> <img src="https://img.shields.io/badge/MCP-server-8A2BE2?style=flat-square" alt="MCP Server"> <img src="https://img.shields.io/badge/macOS%20%7C%20Linux-supported-4CAF50?style=flat-square" alt="macOS and Linux supported"> </p>

_{Fork of <a href="https://github.com/TMSSS05/google-flow-browser-mcp">TMSSS05/google-flow-browser-mcp</a> — adds macOS support and a working reference-image pipeline.}

<br>

✨ Features • 🚀 Quick Start • 🔧 Tools • ⚙️ Configuration • 🛡️ Safety

<br>

</div>

---

🇫🇷 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.

---

✨ Features

<table> <tr> <td width="50%">

🎯 For AI Agents

</td> <td width="50%">

🔒 For Humans

</td> </tr> <tr> <td>

• 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 </td> <td>

• 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 </td> </tr> </table>

---

🚀 Quick Start

Prerequisites

What	Why
Node.js ≥ 18	Runtime for the MCP server
Google Chrome	Required for browser automation
An MCP client	OpenCode, Claude Code, Claude Desktop, or any other MCP-compatible agent
A Google account	To use Google Flow (yours, not shared)

1️⃣ Install

git clone https://github.com/MinaSalib216/google-flow-mcp.git
cd google-flow-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 or Default), and the path before it is your chromeUserDataDir.

⚠️ macOS only: Chrome refuses --remote-debugging-port on your real, OS-default profile directory ("DevTools remote debugging requires a non-default data directory"). Point chromeUserDataDir at a copy of your profile instead:

mkdir -p "$HOME/.google-flow-chrome-profile"
cp -R "$HOME/Library/Application Support/Google/Chrome/Default" \
      "$HOME/.google-flow-chrome-profile/Default"

Then set chromeUserDataDir to ~/.google-flow-chrome-profile and chromeProfile to Default. This preserves your login session without touching your real Chrome profile. Linux is unaffected by this restriction.

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 your MCP client

OpenCode:

./scripts/register-opencode.sh

🔄 Restart OpenCode after registration for the changes to take effect.

Claude Code: add a .mcp.json in your project root:

{
  "mcpServers": {
    "google-flow": {
      "command": "node",
      "args": ["/absolute/path/to/google-flow-mcp/src/index.js"]
    }
  }
}

Any other MCP client: point it at node /absolute/path/to/google-flow-mcp/src/index.js over stdio.

✅ 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

<details> <summary><strong>Which Chrome profile should I use?</strong></summary>

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. </details>

<details> <summary><strong>Can I use this without OpenCode?</strong></summary>

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

Troubleshooting

<details> <summary><strong>Chrome doesn't start</strong></summary>

Make sure Chrome is installed at the expected path. scripts/start-browser.sh auto-detects macOS vs Linux and picks a sensible default (/Applications/Google Chrome.app/... vs /opt/google/chrome/chrome) — override with the CHROME environment variable if yours lives elsewhere. </details>

<details> <summary><strong>"DevTools remote debugging requires a non-default data directory" (macOS)</strong></summary>

Chrome blocks remote debugging on your real, OS-default profile folder. See the macOS callout in step 2 of Quick Start — point chromeUserDataDir at a dedicated copy of your profile instead. </details>

<details> <summary><strong>CDP port already in use</strong></summary>

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

<details> <summary><strong>"Expected account mismatch"</strong></summary>

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

<details> <summary><strong>Flow UI changed and tools don't work</strong></summary>

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

Usage

<details> <summary><strong>How do I generate images?</strong></summary>

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. </details>

<details> <summary><strong>Can I generate videos for free?</strong></summary>

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. </details>

---

🤝 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 — this fork adds macOS support and a working reference-image pipeline.

---

<div align="center"> _{Built with ❤️ for the MCP ecosystem} <br> _{<a href="https://github.com/MinaSalib216/google-flow-mcp/issues">Report Issue</a> · <a href="https://github.com/MinaSalib216/google-flow-mcp/discussions">Discussion</a>} </div>