Skip to content
Back to search

google-flow-browser-mcp

MCP server for controlling Google Flow via browser automation (Playwright + CDP)

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/tmsss05--google-flow-browser-mcp/badge.svg)](/listings/tmsss05--google-flow-browser-mcp)

HTML

<a href="/listings/tmsss05--google-flow-browser-mcp"><img src="/api/listings/tmsss05--google-flow-browser-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 410 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. # 🧠 Google Flow Browser MCP
  3. **Control [Google Flow](https://labs.google/fx/tools/flow) — image & video generation — directly from your AI agent via MCP.**
  4. <p>
  5. <img src="https://img.shields.io/badge/version-1.0.0-blue?style=flat-square" alt="Version 1.0.0">
  6. <img src="https://img.shields.io/badge/node-%3E%3D18-green?style=flat-square" alt="Node >= 18">
  7. <img src="https://img.shields.io/badge/license-MIT-lightgrey?style=flat-square" alt="License MIT">
  8. <img src="https://img.shields.io/badge/MCP-server-8A2BE2?style=flat-square" alt="MCP Server">
  9. <img src="https://img.shields.io/badge/OpenCode-ready-4CAF50?style=flat-square" alt="OpenCode Ready">
  10. </p>
  11. <br>
  12. [✨ Features](#-features) •
  13. [🚀 Quick Start](#-quick-start) •
  14. [🔧 Tools](#-tools) •
  15. [⚙️ Configuration](#️-configuration) •
  16. [🛡️ Safety](#️-safety--ethics)
  17. <br>
  18. </div>
  19. ---
  20. > **🇫🇷 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.**
  21. ---
  22. ## 📸 What It Does
  23. This MCP server connects your AI agent to **[Google Flow](https://labs.google/fx/tools/flow)** — Google's creative suite for image and video generation. Your agent can:
  24. - 🎨 **Generate images** with Nano Banana Pro, Nano Banana 2, or Imagen 4
  25. - 🎬 **Create videos** and scenes with characters
  26. - 🧑 **Manage characters** and scenes in your Flow workspace
  27. - 🖼️ **Use Grid Architect** for batch shot generation
  28. - 🔍 **Discover and control** any Flow tool programmatically
  29. All through your **own Google account** — no API keys, no third-party tokens.
  30. ---
  31. ## ✨ Features
  32. <table>
  33. <tr>
  34. <td width="50%">
  35. ### 🎯 For AI Agents
  36. </td>
  37. <td width="50%">
  38. ### 🔒 For Humans
  39. </td>
  40. </tr>
  41. <tr>
  42. <td>
  43. - **15+ MCP tools** ready to use
  44. - **Smart job queue** — no parallel conflicts
  45. - **Auto-discover UI** — adapts to Flow changes
  46. - **Structured logging** for debugging
  47. - **Safe actions** — resilient click/fill logic
  48. </td>
  49. <td>
  50. - **Your account, your data** — no token sharing
  51. - **No password asked** — ever
  52. - **Clean safety rules** — stops on captcha/verification
  53. - **Config backup** before any modification
  54. - **Single-job queue** — no runaway generation
  55. </td>
  56. </tr>
  57. </table>
  58. ---
  59. ## 🚀 Quick Start
  60. ### Prerequisites
  61. | What | Why |
  62. |------|-----|
  63. | **Node.js ≥ 18** | Runtime for the MCP server |
  64. | **Google Chrome** | Required for browser automation |
  65. | **OpenCode** | AI agent that connects to MCP servers |
  66. | **A Google account** | To use Google Flow (yours, not shared) |
  67. ### 1️⃣ Install
  68. ```bash
  69. git clone https://github.com/TMSSS05/google-flow-browser-mcp.git
  70. cd google-flow-browser-mcp
  71. npm install
  72. ```
  73. ### 2️⃣ Configure your Google profile
  74. ```bash
  75. cp config/flow.config.example.json config/flow.config.json
  76. ```
  77. Edit `config/flow.config.json`:
  78. ```json
  79. {
  80. "expectedAccount": "your.email@gmail.com",
  81. "chromeProfile": "Profile 3",
  82. "chromeUserDataDir": "/home/you/.config/google-chrome"
  83. }
  84. ```
  85. > 💡 **Finding your Chrome profile:**
  86. > 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`.
  87. ### 3️⃣ Make scripts executable
  88. ```bash
  89. chmod +x scripts/*.sh
  90. ```
  91. ### 4️⃣ Start Chrome with CDP
  92. ```bash
  93. ./scripts/start-browser.sh
  94. ```
  95. > This launches Chrome with remote debugging enabled on port 9222 using your configured profile.
  96. ### 5️⃣ Start the MCP server
  97. ```bash
  98. # In a separate terminal:
  99. ./scripts/start-mcp.sh
  100. ```
  101. ### 6️⃣ Register with OpenCode
  102. ```bash
  103. ./scripts/register-opencode.sh
  104. ```
  105. > 🔄 **Restart OpenCode** after registration for the changes to take effect.
  106. ### ✅ Verify it works
  107. ```bash
  108. ./scripts/test-flow-image.sh
  109. ```
  110. ---
  111. ## 🏗️ Architecture
  112. ```
  113. google-flow-browser-mcp/
  114. │
  115. ├── 📂 config/
  116. │ ├── flow.config.example.json # Configuration template
  117. │ └── selectors.map.json # UI selectors (auto-populated)
  118. │
  119. ├── 📂 scripts/
  120. │ ├── start-browser.sh # Launch Chrome + CDP
  121. │ ├── start-mcp.sh # Start the MCP server
  122. │ ├── test-flow-image.sh # Quick integration test
  123. │ └── register-opencode.sh # Register in OpenCode config
  124. │
  125. ├── 📂 src/
  126. │ ├── index.js # MCP server entry point
  127. │ │
  128. │ ├── 📁 browser/ # Chrome & CDP management
  129. │ │ ├── connect.js # CDP connection manager
  130. │ │ ├── launch-profile.js # Chrome profile launcher
  131. │ │ ├── account-check.js # Verify Google account
  132. │ │ └── safe-actions.js # Safe click, fill, detection
  133. │ │
  134. │ ├── 📁 tools/ # All MCP tool implementations
  135. │ │ ├── flow-open.js # Navigate to Flow
  136. │ │ ├── flow-status.js # Connection status
  137. │ │ ├── generate-image.js # Image generation
  138. │ │ ├── generate-video.js # Video generation (setup only)
  139. │ │ ├── download-latest.js # Download generated files
  140. │ │ ├── create-character.js # Create a character
  141. │ │ ├── import-character.js # Import character JSON
  142. │ │ ├── open-characters.js # List characters
  143. │ │ ├── create-scene.js # Create a scene
  144. │ │ ├── open-tools-gallery.js # Open tools gallery
  145. │ │ ├── grid-architect.js # Batch shot generation
  146. │ │ ├── discover-ui.js # UI discovery & mapping
  147. │ │ └── use-flow-tool.js # Generic tool opener
  148. │ │
  149. │ ├── 📁 queue/ # Job management
  150. │ │ └── job-queue.js # Single-job queue
  151. │ │
  152. │ └── 📁 utils/ # Helpers
  153. │ ├── config.js # Config loader
  154. │ ├── logger.js # Structured logging
  155. │ ├── errors.js # Error codes & types
  156. │ ├── file-manager.js # File download/save
  157. │ └── screenshots.js # Screenshot capture
  158. │
  159. └── 📂 output/ # Generated files land here
  160. ```
  161. ---
  162. ## 🔧 Tools
  163. All tools are organized by function for easy discovery.
  164. ### 🌐 Connection & Status
  165. | Tool | Description |
  166. |------|-------------|
  167. | `flow_connect` | Launch Chrome, connect CDP, navigate to Google Flow |
  168. | `flow_disconnect` | Close browser and clean up all connections |
  169. | `flow_status` | Full status: connection, Flow loaded, account, queue state |
  170. | `flow_account_check` | Verify logged-in account matches configured email |
  171. | `flow_screenshot` | Capture a screenshot of the current Flow page |
  172. ### 🎨 Image Generation
  173. | Tool | Description |
  174. |------|-------------|
  175. | `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. |
  176. | `flow_download_latest` | Download the most recently generated file |
  177. ### 🎬 Video Generation
  178. | Tool | Description |
  179. |------|-------------|
  180. | `flow_generate_video` | Set up video generation (Omni Flash, Veo models, custom duration/ratio). ⚠️ **Stops at "ready to generate" — no credit consumed.** |
  181. | `flow_create_scene` | Create a video scene with characters and a text prompt |
  182. ### 👤 Characters
  183. | Tool | Description |
  184. |------|-------------|
  185. | `flow_create_character` | Create a new character with name, description, and optional reference images |
  186. | `flow_import_character` | Import a character from a saved JSON file |
  187. | `flow_open_characters` | Open the characters page and list all existing characters |
  188. ### 🛠️ Tools & Discovery
  189. | Tool | Description |
  190. |------|-------------|
  191. | `flow_open_tools_gallery` | Open the tools gallery and browse available tools |
  192. | `flow_use_tool` | Open any Flow tool by name with optional parameters |
  193. | `flow_use_grid_architect` | Configure Grid Architect for batch shot generation with theme prompts, visual logic, and reference images |
  194. | `flow_discover_ui` | Discover and map all interactive elements (buttons, inputs, headings) on any Flow page |
  195. ### 📊 Queue & Monitoring
  196. | Tool | Description |
  197. |------|-------------|
  198. | `flow_queue_status` | Check job queue: active job, pending queue, completed and failed history |
  199. ---
  200. ## ⚙️ Configuration
  201. Edit `config/flow.config.json` (copy from `config/flow.config.example.json`):
  202. ### 🔑 Essential
  203. | Key | Type | Default | Description |
  204. |-----|------|---------|-------------|
  205. | `expectedAccount` | `string` | — | Your Google account email ✅ **REQUIRED** |
  206. | `chromeProfile` | `string` | `"Profile 3"` | Chrome profile directory name |
  207. | `chromeUserDataDir` | `string` | — | Full path to Chrome user data directory ✅ **REQUIRED** |
  208. | `flowUrl` | `string` | *Flow labs URL* | Google Flow URL (supports `fr`, `en` locales) |
  209. ### 🔧 Advanced
  210. | Key | Type | Default | Description |
  211. |-----|------|---------|-------------|
  212. | `cdpPort` | `number` | `9222` | Chrome DevTools Protocol port |
  213. | `browserMode` | `string` | `"direct-cdp"` | `"direct-cdp"` (recommended) or `"playwright"` |
  214. | `headless` | `boolean` | `true` | Run Chrome in headless mode |
  215. | `locale` | `string` | `"fr"` | UI locale (`"fr"`, `"en"`, etc.) |
  216. ### ⏱️ Timing
  217. | Key | Default | Description |
  218. |-----|---------|-------------|
  219. | `jobTimeoutMs` | `300000` (5 min) | Max job execution time |
  220. | `actionDelayMs` | `800` | Delay between UI actions (anti-detection) |
  221. | `generationPollIntervalMs` | `5000` (5s) | How often to poll for generation completion |
  222. | `maxPollAttempts` | `120` | Max polling attempts before timeout |
  223. | `downloadWaitMs` | `30000` (30s) | Wait time for file download |
  224. ### 🎨 Models & Ratios
  225. | Key | Description |
  226. |-----|-------------|
  227. | `imageModels` | Available models: `Nano Banana Pro`, `Nano Banana 2`, `Imagen 4` |
  228. | `videoModels` | Available models: `Omni Flash`, `Veo 3.1 - Lite/Fast/Quality` |
  229. | `ratios` | Supported aspect ratios: `16:9`, `4:3`, `1:1`, `3:4`, `9:16` |
  230. ---
  231. ## 🛡️ Safety & Ethics
  232. This project is built with **safety-first design**:
  233. | ✅ Principle | How it's enforced |
  234. |-------------|-------------------|
  235. | **Your account only** | Uses your own Google profile — never asks for or stores passwords |
  236. | **No credential theft** | Never exports cookies, tokens, or session data |
  237. | **No bypass** | Stops cleanly on captcha, login walls, or verification challenges |
  238. | **No parallel abuse** | Single-job queue prevents concurrent generation |
  239. | **Credit-safe video** | Video generation sets up parameters but stops before the final "Generate" click (no credit consumed) |
  240. | **Config backup** | Backs up OpenCode config before any modification |
  241. > ⚠️ **This is a browser automation tool.** Use it responsibly and in accordance with Google's Terms of Service.
  242. ---
  243. ## ❓ FAQ
  244. ### Getting Started
  245. <details>
  246. <summary><strong>Which Chrome profile should I use?</strong></summary>
  247. Open Chrome and go to `chrome://version/`. The **Profile Path** shows both your user data directory and profile name. For example:
  248. - `/home/you/.config/google-chrome/Profile 3` → `chromeUserDataDir: "/home/you/.config/google-chrome"`, `chromeProfile: "Profile 3"`
  249. You need a profile where you're already logged into your Google account.
  250. </details>
  251. <details>
  252. <summary><strong>Can I use this without OpenCode?</strong></summary>
  253. 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`.
  254. </details>
  255. ### Troubleshooting
  256. <details>
  257. <summary><strong>Chrome doesn't start</strong></summary>
  258. 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.
  259. </details>
  260. <details>
  261. <summary><strong>CDP port already in use</strong></summary>
  262. 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).
  263. </details>
  264. <details>
  265. <summary><strong>"Expected account mismatch"</strong></summary>
  266. Verify that `expectedAccount` in `config/flow.config.json` matches the email logged into your Chrome profile. Use `flow_account_check` to verify.
  267. </details>
  268. <details>
  269. <summary><strong>Flow UI changed and tools don't work</strong></summary>
  270. Run `flow_discover_ui` to re-map selectors. The `selectors.map.json` will auto-update with new UI element positions.
  271. </details>
  272. ### Usage
  273. <details>
  274. <summary><strong>How do I generate images?</strong></summary>
  275. 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.
  276. </details>
  277. <details>
  278. <summary><strong>Can I generate videos for free?</strong></summary>
  279. `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.
  280. </details>
  281. ---
  282. ## 🤝 Contributing
  283. Contributions are welcome! Please follow these guidelines:
  284. 1. Fork the repository
  285. 2. Create a feature branch (`git checkout -b feature/my-feature`)
  286. 3. Commit your changes (`git commit -m 'Add my feature'`)
  287. 4. Push to the branch (`git push origin feature/my-feature`)
  288. 5. Open a Pull Request
  289. ---
  290. ## 📄 License
  291. [MIT](./LICENSE) © TMSSS05
  292. ---
  293. <div align="center">
  294. <sub>Built with ❤️ for the OpenCode ecosystem</sub>
  295. <br>
  296. <sub>
  297. <a href="https://github.com/TMSSS05/google-flow-browser-mcp/issues">Report Issue</a> ·
  298. <a href="https://github.com/TMSSS05/google-flow-browser-mcp/discussions">Discussion</a>
  299. </sub>
  300. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.