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

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

🎨 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 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