Google Flow Browser MCP

An MCP (Model Context Protocol) server that lets an AI agent drive Google Flow (labs.google/fx/tools/flow) through your own logged-in Chrome profile — generating images, videos, characters, and scenes — without ever sharing your Google credentials with the agent.

This server supports Windows, macOS, and Linux out of the box using unified npm commands that automatically dispatch platform-specific execution.

---

How it works

1. Chrome is launched with --remote-debugging-port (Chrome DevTools Protocol / CDP) using a real Chrome profile that's already signed in to your Google account.
2. The MCP server (src/index.js) connects to that Chrome instance via Playwright's connectOverCDP and drives the Google Flow web app — filling prompts, clicking buttons, reading results.
3. Your AI agent (Claude / OpenCode / any MCP client) talks to the MCP server over stdio and calls tools like flow_generate_image, flow_generate_video, flow_create_character, etc.

Because the agent never touches your Google password — it only sends commands to a browser that's already logged in — there's no credential sharing involved.

---

Prerequisites

• Node.js 18 or later (LTS recommended)
• Google Chrome installed normally (Playwright connects to your real Chrome via CDP — it does not need its own bundled browser for this)
• A Google account already signed in to a Chrome profile (e.g. "Default" or "Profile 1" — any profile works, you just need to tell the config which one)
• (Optional) OpenCode if you want to register this MCP server with it

---

Setup

1. Clone and install dependencies

git clone https://github.com/shaig-mahmudov/google-flow-mcp.git
cd google-flow-mcp
npm install

npm install will also download Playwright's browser binaries. This project doesn't use Playwright's bundled Chromium though — it connects to your real installed Chrome.

2. Find your Chrome profile

You need a Chrome profile that's already signed in to the Google account you want Flow to use.

1. Open Chrome and go to chrome://version
2. Look at Profile Path — note the User Data directory and Profile folder name (e.g. Default, Profile 1, Profile 2).

Default locations by platform:

• Windows:
  • Executable: C:\Program Files\Google\Chrome\Application\chrome.exe (Auto-detected)
  • User Data: C:\Users\<username>\AppData\Local\Google\Chrome\User Data
• macOS:
  • Executable: /Applications/Google Chrome.app/Contents/MacOS/Google Chrome (Auto-detected)
  • User Data: /Users/<username>/Library/Application Support/Google/Chrome
• Linux:
  • Executable: /opt/google/chrome/chrome or /usr/bin/google-chrome (Auto-detected)
  • User Data: /home/<username>/.config/google-chrome

If you don't have a profile signed in yet, sign in to your Google account in any Chrome profile first (Settings → You and Google → Sign in).

⚠️ Close all running Chrome windows for that profile before using this tool — Chrome locks its profile directory while running. To avoid conflicts and profile locking issues, we strongly recommend creating a dedicated Chrome profile specifically for this MCP server (e.g. named "GoogleFlowBot"), signing into your Google account there once, and configuring the server to use it. If you attempt to run the server while actively browsing with the same profile, the connection may fail.

3. Create your config file

Copy the example config and edit it:

Windows (PowerShell):

copy config\flow.config.example.json config\flow.config.json

macOS / Linux:

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

Open config/flow.config.json and set at minimum:

{
  "expectedAccount": "your-email@gmail.com",
  "chromeProfile": "Profile 1" 
}

(Replace "Profile 1" with the actual folder name of your dedicated GoogleFlowBot profile, which you can find in chrome://version)

Note: You only need to set chromeUserDataDir and chromeExecutable if Chrome is installed in a custom location, as the server will otherwise auto-detect them for your current platform.

---

Unified Commands

This project uses a Node.js dispatcher script under the hood, allowing you to run the same npm commands on Windows, macOS, or Linux. The runner will automatically execute the correct scripts (.ps1 for Windows, .sh for Unix).

1. Start Chrome with CDP debugging

npm run start-browser

This launches Chrome with your configured profile and --remote-debugging-port=9222. A Chrome window will open — leave it running.

2. Start the MCP server (optional manual test)

In a separate terminal:

npm run start-mcp

This checks Node is installed, checks Chrome's CDP port is responding, and runs the MCP server. Press Ctrl+C to stop it.

3. Connect to AI Agents

You can automatically configure OpenCode and Gemini CLI in one step:

npm run register

This will automatically find their configuration files and add the Google-Flow MCP server.

(You can also target specific clients: npm run register -- --opencode or --gemini)

Claude Desktop Currently, Claude Desktop requires manual configuration: Add the following to your claude_desktop_config.json:

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

Antigravity Currently, Antigravity requires manual configuration: Add the following to your Antigravity MCP config:

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

(Replace C:/{path}/ with the actual path to the project directory)

Cursor (Codex) Currently, Cursor requires manual UI configuration:

1. Open Cursor Settings > Features > MCP.
2. Click + Add New MCP Server.
3. Name: Google-Flow
4. Type: command
5. Command: node /absolute/path/to/google-flow-mcp/src/index.js

4. Verify everything end-to-end

With Chrome running (step 1), run:

npm run test

This sends a flow_connect tool call to the MCP server over stdio and prints the raw response.

You can also run the Node-based end-to-end test suite:

node scripts/test-e2e.mjs

---

Typical workflow

1. npm run start-browser — once per session, leave the Chrome window open
2. Your AI agent (with this MCP registered) calls:
   • flow_connect — attach to the running Chrome
   • flow_account_check — confirm the right Google account is signed in
   • flow_generate_image — create images in a Flow project
   • flow_create_character — create reusable characters
   • flow_generate_video — create videos, optionally referencing previously generated images/characters via ingredients (@name references)
   • flow_list_mention_options — see what images/characters are available to reference by name
   • flow_create_scene — create a new scene, optionally referencing characters

The MCP server automatically creates a Google Flow project on first use and reuses it for the rest of the session (tracked by project ID), so everything ends up in one place instead of a new project per request.

---

Available tools

Tool	Purpose
flow_connect	Connect to / launch Chrome via CDP, optionally open Flow
flow_disconnect	Close the browser connection
flow_status	Report current connection/page status
flow_account_check	Verify the signed-in Google account matches expectedAccount
flow_discover_ui	Navigate to a Flow page and dump interactive elements (debugging)
flow_generate_image	Generate image(s) from a prompt in the current project
flow_generate_video	Generate video(s), optionally with ingredients/use_character/use_scene references
flow_download_latest	Download the most recently generated asset
flow_create_character	Create a new character (name + description + reference images)
flow_import_character	Import a character from a saved JSON file
flow_open_characters	Open the Characters page for a project
flow_list_mention_options	List images/characters available for @name references
flow_create_scene	Create a new scene, optionally referencing characters
flow_open_tools_gallery	Open Flow's Tools gallery
flow_use_grid_architect	Open the Grid Architect tool
flow_use_tool	Use an arbitrary tool from the Tools gallery
flow_screenshot	Take a debug screenshot of the current page
flow_queue_status	Check the status of queued generation jobs

---

Configuration reference

All settings live in config/flow.config.json (copy from flow.config.example.json). Key fields:

Field	Description	Default
expectedAccount	Google account email flow_account_check expects	(required)
chromeExecutable	Full path to chrome executable	auto-detected
chromeUserDataDir	Path to Chrome's "User Data" folder	auto-detected
chromeProfile	Profile folder name (e.g. Default, Profile 1)	Default
cdpPort	Chrome DevTools Protocol port	9222
flowUrl	Base Google Flow URL	https://labs.google/fx/tools/flow
headless	Run Chrome headless	true
jobTimeoutMs	Max time to wait for a generation job	300000
imageModels / videoModels	Display name → internal model ID maps	see example config
ratios / videoRatios / durations / quantities	Allowed generation parameters	see example config

---

Troubleshooting

"Chrome not found" Make sure Chrome is installed normally. If it is in a custom path, set chromeExecutable in config/flow.config.json.

"Chrome profile not found" Double-check chromeUserDataDir + chromeProfile against chrome://version in your browser.

"CDP port 9222 not responding" Run npm run start-browser first and leave that Chrome window open.

Google sign-in gets blocked ("This browser may not be secure") This is why the server connects to your existing signed-in Chrome profile. Ensure chromeUserDataDir / chromeProfile points to the profile you logged in with.

The agent creates a new Flow project every time The server tracks one project per session by ID and reuses it. If this happens, check the logs for Session project no longer reachable and start a fresh session.

---

Project layout

config/
  flow.config.example.json   # template — copy to flow.config.json
  selectors.map.json         # auto-updated cache from flow_discover_ui
scripts/
  run.js                     # OS-independent command dispatcher
  start-browser.ps1 / .sh    # launch Chrome with CDP debugging
  start-mcp.ps1 / .sh        # run the MCP server (manual check)
  register-opencode.ps1 / .sh# register this server with OpenCode
  test-flow-image.ps1 / .sh  # quick flow_connect smoke test
  test-e2e.mjs               # multi-tool Node end-to-end test
src/
  index.js                   # MCP server entry point
  browser/                   # Chrome/CDP connection logic
  navigation/                # project navigation, @ mention references
  tools/                     # one file per MCP tool
  utils/                     # config, logging, screenshots, file output

---

Safety notes

• This server only automates a browser you already control and are signed into — it does not store, transmit, or need your Google credentials.
• Image and video generation consume Google Flow credits. Generation tools default to safe "prepare only" behavior (auto_confirm: false).
• config/flow.config.json is gitignored — do not commit it.

---

License

This project is licensed under the MIT License.