🧠 Google Flow Browser MCP

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

Fork of TMSSS05/google-flow-browser-mcp — adds macOS support and a working reference-image pipeline.

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

✨ 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

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

🎨 Image Generation

🎬 Video Generation

👤 Characters

🛠️ Tools & Discovery

📊 Queue & Monitoring

⚙️ Configuration

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

🔑 Essential

🔧 Advanced

⏱️ Timing

🎨 Models & Ratios

🛡️ Safety & Ethics

This project is built with safety-first design:

⚠️ 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 Code, 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. 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.

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.

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