# Google Flow MCP Server: Veo 3.1 and Omni AI Video Generation for Claude, Cursor and AI Agents

[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/Model%20Context%20Protocol-server-blue)](https://modelcontextprotocol.io)
[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)
[![Google Flow](https://img.shields.io/badge/Google%20Flow-Veo%203.1%20%7C%20Omni%20%7C%20Nano%20Banana-orange)](https://flow.google.com)

**google-flow-mcp** is an open source **MCP server for Google Flow** (flow.google.com), Google's AI filmmaking
studio. It lets Claude, Claude Code, Cursor or any Model Context Protocol client **create consistent AI characters,
generate Veo 3.1 and Omni videos with them, assemble scenes, export finished MP4s, chat with the Flow agent and set
agent instructions**. In short, it automates everything you normally click through in the Google Flow UI.

Use it to automate AI video production: short-form reels, AI influencer content, storyboards, ads and
multi-shot stories with the same character in every clip.

> **Unofficial.** Not affiliated with or endorsed by Google. It works with Flow's private web app, which can change
> at any time. Use your own account, follow Google's terms, and keep an eye on your credits.

---

## Table of contents

- [Features](#features)
- [How it works](#how-it-works)
- [Quick start](#quick-start)
- [Connect to Claude Desktop, Claude Code or Cursor](#connect-to-claude-desktop-claude-code-or-cursor)
- [Tools reference](#tools-reference)
- [Example prompts](#example-prompts)
- [Credits and safety](#credits-and-safety)
- [Status and limitations](#status-and-limitations)
- [FAQ](#faq)
- [Contributing](#contributing)
- [License](#license)

## Features

- **Consistent characters.** Create reusable Flow characters with a generated portrait, a voice (30 built-in voices)
  and personality notes, then feature them in any clip so they look the same every time.
- **AI video generation.** Generate clips with **Omni 1.1 Flash** (4 to 10 s, 360p or 720p) or **Veo 3.1 Lite, Fast
  and Quality**, from text or with characters and reference images as ingredients.
- **Video editing.** Change an existing clip with a plain instruction ("make it night, add rain").
- **Image generation.** Nano Banana images for references, storyboards and start frames.
- **Scenes and export.** Build a scene timeline in Flow, then export the whole scene to a single MP4 (ffmpeg
  normalises size, frame rate and audio).
- **Flow agent.** Talk to Flow's built-in creative agent, attach characters, and approve its generations within a
  credit budget.
- **Agent instructions and model defaults.** Manage the project's Agent instructions, default image and video models,
  aspect ratios, counts and the "ask before spending credits" setting.
- **Credit guardrails.** Every generating call reads Flow's own price quote first, refuses above your cap and supports
  `dry_run`.
- **Model catalog.** Lists every model with its mode, duration, resolution and credit price.

## How it works

The server drives a Chrome tab that you are signed in to, using Playwright:

1. **Reads and edits** (projects, characters, scenes, clips, instructions, defaults, job status, media links) use
   Flow's own web API from inside that tab. This is fast and reliable.
2. **Generation** (portraits, images, videos, edits, agent chat) goes through Flow's real UI. The server attaches
   ingredients, picks settings, types the prompt and presses Generate, the same way you would. Flow protects generation
   with reCAPTCHA Enterprise and refuses requests that don't come from its UI, so this project deliberately does not
   try to bypass that. If Flow declines a request, you get Flow's error back and nothing is retried.

Your password and cookies never leave your browser. The server stores nothing except an optional local Chrome
profile.

## Quick start

Requirements: **Node.js 20+**, **Google Chrome**, a Google account with Flow access, and **ffmpeg** on your PATH
(only needed for scene export).

```bash
git clone https://github.com/RohaanA/google-flow-mcp.git
cd google-flow-mcp
npm install
npm run build
npm test
```

Pick one way to give the server a signed-in browser.

**Option A: your own Chrome (recommended).** Start Chrome with remote debugging, sign in at flow.google.com and keep
the window open.

```bash
# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir="$HOME/.flow-chrome"

# Windows (PowerShell)
& "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir="$env:USERPROFILE\.flow-chrome"

# Linux
google-chrome --remote-debugging-port=9222 --user-data-dir="$HOME/.flow-chrome"
```

Then set `FLOW_CDP_URL=http://127.0.0.1:9222`.

**Option B: a dedicated profile.** Run `npm run login`, sign in to Flow in the window that opens, then close it. The
server will launch Chrome with that profile (`~/.google-flow-mcp/profile`).

## Connect to Claude Desktop, Claude Code or Cursor

Add the server to your MCP client config (for example `claude_desktop_config.json`, `.mcp.json` or Cursor's
`mcp.json`):

```json
{
  "mcpServers": {
    "google-flow": {
      "command": "node",
      "args": ["/absolute/path/to/google-flow-mcp/dist/index.js"],
      "env": {
        "FLOW_CDP_URL": "http://127.0.0.1:9222",
        "FLOW_MAX_CREDITS_PER_CALL": "20",
        "FLOW_OUTPUT_DIR": "/absolute/path/to/FlowExports"
      }
    }
  }
}
```

With Claude Code you can also run:

```bash
claude mcp add google-flow -e FLOW_CDP_URL=http://127.0.0.1:9222 -- node /absolute/path/to/google-flow-mcp/dist/index.js
```

| Environment variable | Default | Purpose |
|---|---|---|
| `FLOW_CDP_URL` | unset | Attach to your running Chrome instead of launching one |
| `FLOW_PROFILE_DIR` | `~/.google-flow-mcp/profile` | Chrome profile for option B |
| `FLOW_CHROME_PATH` / `FLOW_BROWSER_CHANNEL` | `chrome` | Which browser to launch |
| `FLOW_HEADLESS` | `0` | Launch headless (read-only use) |
| `FLOW_MAX_CREDITS_PER_CALL` | `20` | Default credit cap for each generating call |
| `FLOW_OUTPUT_DIR` | `~/FlowExports` | Where downloads and scene exports go |

## Tools reference

| Area | Tool | What it does |
|---|---|---|
| Account | `flow_status` | Checks the browser session and returns your credit balance |
| | `flow_list_models` | Omni and Veo models with mode, duration, resolution and credit price |
| | `flow_list_voices` | Voices you can give a character |
| Projects | `flow_list_projects`, `flow_create_project` | List or create Flow projects |
| | `flow_get_project` | Characters, generations, scenes with clips, agent instructions and defaults |
| Characters | `flow_create_character` | Name, generated portrait, voice and personality |
| | `flow_update_character` | Rename, change voice or personality |
| | `flow_regenerate_portrait` | Change a character's look with an instruction |
| Images | `flow_generate_image` | Nano Banana images, optionally with characters or reference images |
| Video | `flow_generate_video` | Text-to-video or character/reference video; `wait`, `add_to_scene_id`, `dry_run`, `max_credits` |
| | `flow_edit_video` | Edit an existing clip with an instruction |
| | `flow_video_status` | Poll or wait for jobs; returns signed video URLs |
| | `flow_get_media`, `flow_download_media` | Fetch or download images and videos |
| Scenes | `flow_create_scene`, `flow_add_clips_to_scene` | Build an ordered scene timeline |
| | `flow_export_scene` | Join a scene's clips into one MP4 |
| Agent | `flow_agent_chat`, `flow_agent_respond`, `flow_list_agent_sessions` | Chat with Flow's agent and approve or reject its credit requests |
| Settings | `flow_set_agent_instructions` | Add, replace or remove the project's Agent instructions |
| | `flow_set_generation_defaults` | Default image and video models, aspect, count and credit approval policy |

## Example prompts

Paste these into Claude (or any MCP client) once the server is connected:

- "Create a Flow project called *Street Food Diaries* and a character Maya: late 20s travel vlogger, curly dark hair,
  olive jacket, voice aoede, upbeat and curious."
- "Make three 4 second 360p vertical clips of Maya at a night market, wait for them, put them in a new scene and export
  it."
- "What would a 720p 8 second Omni clip of Maya cost? Do a dry run."
- "Add an agent instruction: always shoot handheld vlog style in 9:16 with natural light."
- "Ask the Flow agent to storyboard a 30 second reel with Maya, and approve anything under 20 credits."

## Credits and safety

- Generating spends **your Flow credits**. Every generating tool reads Flow's own quote ("Generating will use N
  credits") and refuses when it is above `max_credits` (default 20, or `FLOW_MAX_CREDITS_PER_CALL`).
- Use `dry_run: true` to see the price without generating. 360p and 4 s Omni clips are the cheapest drafts.
- `flow_agent_chat` never approves the agent's spending unless you set `max_credits`.
- Generation runs one job at a time in a single tab. Avoid using that tab yourself while a job is running.

## Status and limitations

Tested against a live account:

- reading projects, characters, scenes, media and job status
- creating and updating characters
- creating scenes and adding clips
- agent instructions, defaults and credit approval policy
- character-reference video generation through the UI; the request Flow's UI sent matches this project's request
  builder field for field (see `test/protocol.test.mjs`)

Implemented but less tested:

- portrait creation, image generation, video edit and agent chat through the UI
- Veo menus, which may offer different durations than Omni

Not supported yet:

- start/end-frame video
- extend
- upsample
- media upload

Pull requests welcome.

Because Flow's web app is private and changes often, selectors or payloads can break after a Google update. The
protocol notes in [PROTOCOL.md](PROTOCOL.md) and the tests make fixes quick.

## FAQ

**Is there an official Google Flow API?**
Not for Flow itself. Google offers Veo through the Gemini API and Vertex AI, which is the stable choice for pure
video generation. This project is for people who want Flow's features (characters, scenes, the Flow agent, Omni
models) from an AI agent.

**Does this work with Claude Code, Cursor, Windsurf or other MCP clients?**
Yes. It is a standard stdio MCP server, so any Model Context Protocol client can use it.

**Can I generate Veo 3.1 videos with consistent characters?**
Yes. Create a character once, then pass its id (or name) in `character_ids`. The clip uses Flow's
reference-to-video models so the character stays consistent.

**Does it bypass Flow's limits or captcha?**
No. Generation goes through Flow's normal UI and uses your own account, credits and limits. If Flow refuses a
request, the tool reports it.

**Is my Google password or cookie stored?**
No. The server controls a browser you signed in to yourself and never reads or saves your credentials.

**Why does it need Chrome?**
Flow only allows generation from its own web app, so the server works through a real, signed-in browser session.

## Contributing

Issues and pull requests are welcome, especially:

- start/end-frame video support
- Veo-specific settings
- uploads
- selector fixes after Flow updates

Run `npm test` before opening a PR, and never commit real account ids, tokens or signed URLs in fixtures.

## Keywords

Google Flow API, Google Flow MCP, Veo 3.1 MCP server, Veo 3 automation, Omni video, Nano Banana, AI video
generation, AI filmmaking, consistent AI characters, AI influencer video, text to video, reference to video, Claude
MCP, Claude Code, Cursor MCP, Model Context Protocol, Playwright automation, scene export, ffmpeg.

## License

[MIT](LICENSE). Google, Google Flow, Veo and Nano Banana are trademarks of Google LLC. This project is independent
and unofficial.