Skip to main content
Glama

flow-mcp — Google Flow MCP Server

A standalone MCP server for Google Flow (split off from media-gen-mcp): 0-credit AI image generation + billed video generation (Veo / abra), all driven through your local Chrome session (CDP page context) — no API key, no quotas, no third-party relay.

  • Image generation / image upscaling / upload / status query / download / delete / share / cancel / character entities: all 0 credits

  • Video generation: consumes Google Flow credits (abra 7-20 / veo lite 10 / fast 20 / quality 100 per item; 1080p upscaling 0) — explicitly warned in the tool description, used by default only when the user explicitly asks

Installation

Prerequisites (one-time):

  1. Install lasso locally (the Chrome launcher in the CC full-interaction harness)

  2. Launch Chrome with CDP and sign in to labs.google:

lasso launch-chrome --port 9223 --mode visible   # 首次:窗口出现,完成 Google 登录(2FA 同)
# 之后每天只需:hidden 模式静默驻留
lasso launch-chrome --port 9223
  1. Open any project page at https://labs.google/fx/tools/flow in that Chrome (keep it running)

Connect to Claude Code:

claude mcp add flow-mcp -- node /path/to/flow-mcp/dist/index.js
# 或发布后:npx flow-mcp-server

Can be connected alongside media-gen-mcp without conflicts (see "Coexistence with media-gen-mcp" below).

Related MCP server: Grok Image Generation MCP Server

Tools (4)

Tool

Credits

Purpose

flow_generate_image

0

Text-to-image / image-to-image (base image + reference image) / 2K upscaling. NARWHAL (Nano Banana 2, default) / HARBOR_SEAL / GEM_PIX_2 (Nano Banana Pro). Supports aspect (16:9/9:16/1:1/3:4/4:3) and seed for exact reproduction

flow_generate_video

🔴 Billed

Video submission (t2v/i2v/r2v/first-last frames/extend/edit/upscale). Submit only, no waiting — returns a mediaId handle immediately

flow_status

0

One-stop introspection: credit balance / live model catalog (credit price and latency per key) / media list / single-media status and download / batch delete / public share links / cancel in-progress tasks. Also the polling path for video handles

flow_entity

0

Character entities: create character card / bind one of 30 preset voices / bind appearance image

Typical flow:

flow_status                                    # 先看:余额 + 目录(per-key creditsAtServiceTier)
flow_generate_image(prompt=..., aspect="16:9") # 0 积分生图,产出落盘并回传 mediaId+seed
flow_generate_video(model="abra_t2v_8s", ...)  # 🔴 计费提交 → 返回 mediaId 句柄(不阻塞)
flow_status(mediaId="...")                     # 轮询(0 积分;in_progress 会给 retry_after_seconds)
flow_status(mediaId="...", download=true)      # completed 后落盘 mp4

Configuration (shares one file with media-gen-mcp)

Config file: ~/.media-gen-mcp/config.json (both packages read the same file — "different implementation channels for the same feature" are enabled/disabled uniformly in one file). The directory name follows the historical name, do not change it (the Flow project ID is permanently recorded in ~/.media-gen-mcp/flow-project.json; renaming would orphan it).

{
  "flow": {
    "enabled": true,
    "imageRouting": "prefer",
    "videoRouting": "explicit-only",
    "toolDeadlineMs": 110000
  },
  "providers": {
    "flow": { "cdpPort": 9223 }
  }
}

Field

Default

Purpose

flow.enabled

true

false = S000 gate: the 4 tools are still registered, but any call immediately returns a [flow] S000 structured error (with built-in fix guidance). A session restart is required after changing the config

flow.imageRouting

"prefer"

prefer = the image tool description injects a "0-credit first" hint (soft routing); on-demand = used only when the user explicitly asks for Flow

flow.videoRouting

"explicit-only"

explicit-only (credit red line) = the video tool is used only when the user explicitly requests Flow/Veo/abra; prefer = used as the first choice (still warns about billing)

flow.toolDeadlineMs

110000

Hard cap for a single tool call (prevents hangs; on timeout returns [flow] S410, generation continues server-side and can be recovered via flow_status)

providers.flow.cdpPort

9223

CDP port (matches lasso launch-chrome --port)

providers.flow.projectId

(default)

When absent, reads the permanent project from flow-project.json (recommended — the project ID is reused permanently)

providers.flow.models.video.default

(none)

Deliberately no built-in default: video is billed, so model must be passed explicitly or configured explicitly here

See config.example.json for a full example.

Coexistence with media-gen-mcp

  • Both packages share ~/.media-gen-mcp/config.json; media-gen's own imageProviderPriority / videoProviderPriority chain only takes effect within its own package

  • After the split, cross-package priority = this package's tool-description soft routing (imageRouting/videoRouting guide Claude to prefer flow_generate_image) + the enabled master switch — there is no cross-package hard redirect (the two packages are physically invisible to each other; an honest design)

  • flow-project.json / flow-entities.json belong to this package; after Flow is removed from the media-gen side, it no longer reads or writes them

Error code quick reference ([flow] S<code>)

Code

Meaning

Resolution

S000

Config disabled

Follow the guidance in the error to set flow.enabled back to true, restart the session

S100

CDP unreachable

lasso launch-chrome --port 9223

S101

No labs.google page

Open the Flow project page in that Chrome

S102

Not signed in

Complete the labs.google sign-in in that Chrome

S104

reCAPTCHA failed

Stay on the Flow page and retry

S1xx others

Environment prerequisite

Retry once the environment is ready; image generation can fall back to other image tools

S2xx

Page fetch failed

Check the upstream response snippet in the message

S300/S301/S303

Model/parameter/mode validation

Follow the message guidance to change the key or parameters (intercepted before submission, zero cost)

S400

mediaId not in this project

Call flow_status without arguments to view all media

S402

Incomplete download

Just retry

S410

Tool-layer deadline (anti-hang)

Generation is still running server-side; recover via flow_status without arguments

Environment requirements

  • Node.js ≥ 18

  • Local Chrome (launched via lasso with --remote-debugging-port=9223) signed in to labs.google

  • FFmpeg bundled with the package (ffmpeg-static; used only for output validity self-check, automatically degrades to a notice when missing)

License

MIT

Available Tools

4 tools
flow_entityA

Google Flow character entities (角色实体, ZERO-CREDIT). Create/update CHARACTER entities and bind a preset voice for later audio/character generation. Create: tRPC flow.createEntity {projectId, collectionId:""} (empty string passes zod — no collection needed); update: PATCH /v1/flow/entities with dotted updateMask (displayName / characterInfo.audioReferences=[{presetVoiceId}] / characterInfo.imageReferences=[{workflowId}]). Entity images attach via imageMediaIds (completed image mediaIds from flow_generate_image; the workflowId mapping is resolved automatically from project workflows). 30 preset voices are star-named (achernar/charon/kore/…) with descriptions — list them via action=voices or flow_status preset_voices.

LIMITATION (honest): Flow has NO entity read endpoint (projectContents has no entities key; collections REST is CORS-blocked in page context) — only entities created via this tool are tracked, in a local mirror ~/.media-gen-mcp/flow-entities.json (aligned with flow-project.json precedent). action=list returns the mirror, not a server query.

WHEN: 角色卡 / 建角色 / character entity / bind voice / 角色绑定语音 / 绑定形象图.

NEXT: generate the character image first (flow_generate_image), then flow_entity(action=create, displayName=…, imageMediaIds=[…], presetVoiceId=…) wires it up; all operations are 0-credit.

Multilingual triggers: 角色 · 实体 · character · entity · voice binding (zh/en).

Inputs: action, entityId, displayName, imageMediaIds, +1 more.

flow_generate_imageA

PREFER this tool for AI image generation — 0 credits, no API key, no quota (Google Flow via your local Chrome CDP session). Only fall back to other image tools (e.g. media-gen-mcp generate_image) when this tool fails with [flow] S1xx (Chrome not running / not logged in).

Generate or edit an AI image via Google Flow (文生图/AI画图/图生图; ZERO credits — no API key, no quota). Backed by the LOCAL Chrome session via CDP (lasso launch-chrome --port 9223, logged into labs.google). Output downloads locally and the path is returned.

WHEN: user wants photorealistic or illustrated AI images (写实图/插画/概念图). Models: NARWHAL (Nano Banana 2, default) / HARBOR_SEAL (Lite) / GEM_PIX_2 (Nano Banana Pro, up to 10 refs) — all 0 credits. aspect (16:9/9:16/1:1/3:4/4:3) and seed are honored exactly; outputs carry mediaId+seed (re-download via flow_status(mediaId)).

Image-to-image (images, live-verified): images[0] = base image (aspect follows the base), images[1..10] = references — each uploaded to the Flow project first (0 credits).

Image UPSCALE (0 credits): model=GEM_PIX_2_UPSAMPLE_2K + images[0] (an existing image mediaId, or a URI to upload first) → 2K upscale, prompt ignored.

NEXT: check the catalog/credits via flow_status (no args). Only fall back to other image tools on [flow] S1xx (Chrome not running).

Multilingual triggers: 画像 · imagen · image · Bild · изображение · imagem (ja/es/fr/de/ru/pt).

Inputs: prompt (required), n, name, seed, +6 more.

flow_generate_videoA

🔴 BILLS GOOGLE FLOW CREDITS (abra 7-20 / veo lite 10 / fast 20 / quality 100 per clip; upsampler_1080p = 0). USE ONLY when the user explicitly asks for Flow / Veo / abra video (config flow.videoRouting=explicit-only — the default, credits red line).

Submit an AI video generation to Google Flow (文生视频/图生视频/首尾帧/参考图/延长/编辑/超分). SUBMIT-ONLY: returns a mediaId handle immediately (never blocks ~2-4min generation) — poll with flow_status(mediaId=…) until status=completed, then re-call with download=true to save the mp4.

Model = full usage key (live catalog via flow_status): t2v (text) / i2v (+image) / r2v (+images 1-10) / interpolation or _fl (+keyframes exactly 2) / extension (+videoMediaId, e.g. veo_3_1_extension_lite) / upsampler (+videoMediaId, veo_3_1_upsampler_1080p = 0 credits; 4k tier-locked) / edit (+videoMediaId + prompt = the edit instruction, abra_edit 20 credits, wire probe-verified). Mnemonic + durationSeconds also works (abra_t2v + 8 → abra_t2v_8s). durationSeconds ∈ {4,6,8,10}s (off-grid snaps nearest), ratio 16:9/9:16 only, ONE clip per call — repeat calls for x2-x4 (each bills credits and gets its own seed).

NEXT: flow_status (no args) for the live catalog with per-key creditsAtServiceTier before choosing a key; after submit, flow_status(mediaId=…) { download: true } polls & fetches.

Multilingual triggers: 動画 · vídeo · vidéo · Video · видео · vídeo (ja/es/fr/de/ru/pt).

Inputs: prompt (required), seed, image, model, +7 more.

flow_statusA

Google Flow introspection / media status / download / delete / share / cancel (ZERO-CREDIT; 零消耗自省/状态查询/媒体下载/媒体删除/分享链接/取消生成) — ALSO the polling path for flow_generate_video handles. Backed by the LOCAL Chrome session via CDP (lasso launch-chrome --port 9223, logged into labs.google) — every call runs as page-context fetch, no API keys needed. With NO mediaId: full snapshot (login email, credits balance, dynamic image/video model catalog with per-key creditsAtServiceTier + generationTimeSeconds, 30 preset voices, project media list). With mediaId: one media's generation status (+ download the finished mp4/png locally). With deleteMediaIds: batch-delete project media (0 credits, IRREVERSIBLE — keeps polling payloads small). With shareMediaIds: create public share links (0 credits). With cancelMediaIds: cancel in-flight generations (0 credits). NEVER submits generation — video/image submission goes through flow_generate_video / flow_generate_image (video costs credits: abra 7-20, veo lite 10 / fast 20 / quality 100 per clip; images & upscaling are 0-credit).

WHEN: preflight before generation; poll a submitted mediaId (the async handle from flow_generate_video); fetch an already-generated asset; check remaining credits; clean up accumulated media; share a result; cancel a wrong submission before it finishes.

NEXT: flow_generate_video(model="abra_t2v_8s") submits → returns mediaId handle; flow_status(mediaId=…) tracks it (in_progress → retry_after_seconds); status=completed + download=true saves the mp4.

Multilingual triggers: flow 状态 · flow 积分 · Flow status (zh/en).

Inputs: name, outDir, mediaId, download, +4 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.6/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a completely distinct purpose: video generation, image generation, status/introspection (including download/delete/share/cancel), and character entity management. There is zero overlap or ambiguity between them, even for an agent scanning descriptions.

    Naming Consistency4/5

    All tools share the 'flow_' prefix, creating a clear namespace. Two tools use verb_noun (flow_generate_video, flow_generate_image) while the others are simply noun-like (flow_status, flow_entity), but the pattern is still predictable and readable. Minor deviation from a strict verb_noun convention.

    Tool Count4/5

    Four tools is on the small side but well-suited for a focused media-generation server. Each tool covers a necessary capability (generate video, generate image, manage/inspect, and entity handling). The count feels slightly thin but not incomplete for the domain.

    Completeness4/5

    The surface covers the full lifecycle: generation (video/image), status polling, download, delete, share, cancel, and entity CRUD (via flow_entity and flow_status). Minor gaps exist (e.g., no explicit list/update for media aside from status, but those are handled through flow_status arguments), so agents can accomplish all expected workflows.

    Related MCP Connectors

    Related MCP Servers