flow-mcp — Google Flow MCP Server

Google Flow 的独立 MCP server(从 media-gen-mcp 分离):0 积分 AI 生图 + 计费视频生成(Veo / abra),全部经你本机的 Chrome 会话(CDP 页面上下文)驱动 —— 无 API key、无配额、不走第三方转发。

• 生图 / 图片放大 / 上传 / 状态查询 / 下载 / 删除 / 分享 / 取消 / 角色实体:全部 0 积分
• 生视频:消耗 Google Flow 积分(abra 7-20 / veo lite 10 / fast 20 / quality 100 每条;1080p 超分 0)—— 工具描述里显式警示,默认只在用户点名时使用

安装

前置(一次性):

1. 本机安装 lasso(CC 全交互抓手中的 Chrome 启动器)
2. 启动带 CDP 的 Chrome 并登录 labs.google:

lasso launch-chrome --port 9223 --mode visible   # 首次:窗口出现,完成 Google 登录(2FA 同)
# 之后每天只需:hidden 模式静默驻留
lasso launch-chrome --port 9223

3. 在该 Chrome 打开 https://labs.google/fx/tools/flow 任意项目页(保持运行)

接入 Claude Code:

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

与 media-gen-mcp 可同时接入,互不冲突(见下方「与 media-gen-mcp 共存」)。

工具(4 个)

工具	积分	用途
flow_generate_image	0	文生图 / 图生图(底图+参考图)/ 2K 放大。NARWHAL(Nano Banana 2,默认)/ HARBOR_SEAL / GEM_PIX_2(Nano Banana Pro)。支持 aspect(16:9/9:16/1:1/3:4/4:3)与 seed 精确复现
flow_generate_video	🔴 计费	视频提交(t2v/i2v/r2v/首尾帧/延长/编辑/超分)。只提交不等待,立刻返回 mediaId 句柄
flow_status	0	一站式自省:积分余额 / 实时模型目录(每个 key 的积分价与耗时)/ 媒体列表 / 单媒体状态与下载 / 批量删除 / 公开分享链接 / 取消生成中任务。也是视频句柄的轮询路径
flow_entity	0	角色实体:建角色卡 / 绑 30 选 1 预设语音 / 绑形象图

典型流程:

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

配置(与 media-gen-mcp 共享一个文件)

配置文件:~/.media-gen-mcp/config.json(两包读同一份 —— 「同一功能的不同实现渠道」在一个文件里统一开/关)。目录名沿用历史名,勿改(Flow 项目 ID 永久记录在 ~/.media-gen-mcp/flow-project.json,改名会孤儿化)。

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

字段	默认	作用
flow.enabled	true	false = S000 门禁:4 个工具仍注册,但调用即刻返回 [flow] S000 结构化错误(自带修复指引)。改配置后须重启会话
flow.imageRouting	"prefer"	prefer = 生图工具描述注入「0 积分优先」引导(软路由);on-demand = 仅当用户点名 Flow 时使用
flow.videoRouting	"explicit-only"	explicit-only(积分红线)= 视频工具仅在用户显式要求 Flow/Veo/abra 时使用;prefer = 作为首选(仍警示计费)
flow.toolDeadlineMs	110000	单次工具调用硬上限(防卡死;超时返回 [flow] S410,生成在服务端继续,可经 flow_status 找回)
providers.flow.cdpPort	9223	CDP 端口(与 lasso launch-chrome --port 一致)
providers.flow.projectId	(缺省)	缺省读 flow-project.json 的永久项目(推荐 —— 项目 ID 永久复用)
providers.flow.models.video.default	(无)	刻意无内置默认:视频计费,必须显式传 model 或在此显式配置

完整示例见 config.example.json。

与 media-gen-mcp 共存

• 两包共享 ~/.media-gen-mcp/config.json;media-gen 自己的 imageProviderPriority / videoProviderPriority 链只在它包内生效
• 分离后的跨包优先级 = 本包工具描述软路由(imageRouting/videoRouting 引导 Claude 选 flow_generate_image 优先)+ enabled 总闸 —— 不存在跨包硬重定向(物理上两包互不可见,诚实设计)
• flow-project.json / flow-entities.json 归本包;media-gen 侧摘除 Flow 后不再读写

错误码速查([flow] S<code>)

码	含义	处置
S000	配置已禁用	按错误里的指引把 flow.enabled 改回 true,重启会话
S100	CDP 不可连	lasso launch-chrome --port 9223
S101	无 labs.google 页面	在该 Chrome 打开 Flow 项目页
S102	未登录	在该 Chrome 完成 labs.google 登录
S104	reCAPTCHA 失败	停留在 Flow 页面重试
S1xx 其余	环境前置	环境就绪后重试;生图可回落其他图像工具
S2xx	页面 fetch 失败	看 message 内的上游响应片段
S300/S301/S303	模型/参数/模式校验	按 message 指引换 key 或参数(提交前拦截,零消耗)
S400	mediaId 不在本项目	不带参数调 flow_status 查看全部 media
S402	下载不完整	直接重试
S410	工具层截止(防卡死)	生成仍在服务端进行;flow_status 不带参数找回

环境要求

• Node.js ≥ 18
• 本机 Chrome(经 lasso 以 --remote-debugging-port=9223 启动)并登录 labs.google
• FFmpeg 随包自带(ffmpeg-static;仅用于产物合法性自检,缺失时自动降级为提示)

License

MIT