gflow-mcp
Unofficial Python SDK, CLI, and MCP server for Google Flow that enables project creation and management, live AI credit checks, model discovery, Nano Banana image generation, Veo 3.1/Omni 1.2 video generation with start/end frames and references, video upscaling and extension, frame extraction, media downloads, and Scene Builder multi-clip timeline editing and MP4 stitching.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
gflow-py
Unofficial Agent-native Python SDK, CLI (gflow), Dual-Mode MCP Server (gflow-mcp), and Agent Skill for Google Flow — modeled directly after notebooklm-py.
Turn Google Flow's web creative studio (Veo 3.1, Omni 1.2 Flash, Nano Banana Pro / 2, and Scene Builder) into programmable Python APIs, shell commands, local IDE tools, and remote claude.ai connectors.
Features
Hybrid Zero-API-Key Architecture:
Pure
httpx(batchexecuteJSPB RPCs) for instant (~50ms) project management, live credit checks, model discovery, status polling, media downloads, frame capture, and Scene Builder timeline editing/stitching.Lazy Headless Playwright Enterprise reCAPTCHA invoked only on mutations that require
grecaptcha.enterprise.execute(UPLOAD_IMAGE,IMAGE_GENERATION,VIDEO_GENERATION).
Full Google Flow Studio Coverage:
Account & Models: Live AI credits & renewal timestamp (
gflow usage), full video/image model catalog (gflow models).Projects:
list,create,rename,delete,use(active project context), andmediainspection.Nano Banana Image Generation: Nano Banana Pro (
GEM_PIX_2), Nano Banana 2 (NARWHAL), and Imagen (IMAGEN_3_5) with multi-reference character/style consistency and base-image editing.Veo 3.1 & Omni 1.2 Video Generation:
Text-to-Video (
YhhmEf/IJhj9c)Start-Frame Image-to-Video (
eb1hJf)Start + End Frame Interpolation (
nprQif)Multi-Reference Ingredients-to-Video (R2V) (
MZZa6b)Video Extend (
fZytfe) & 1080p / 4K Upsample (p0UkFb)Video Frame Extraction (
fdJi4e— capture any timestamp as a reusable imagemedia_id)
Scene Builder: Create multi-clip timelines, append/insert clips, reorder, trim in/out timestamps, remove clips, and render/stitch continuous MP4 exports (
GjQLTd+IxdSwd).
Dual-Mode MCP Server (
gflow-mcp):stdio(default) for Antigravity, Claude Code, Claude Desktop, Cursor, and Codex.httpwith built-in Self-Hosted Single-Password OAuth 2.1,MultiAuthstatic bearer support, DNS-rebindingHostguard, and HMAC-signed/files/dl/{token}&/files/ul/{token}out-of-band media streaming & browser image upload links forclaude.aiCustom Connectors over Tailscale Funnel or Cloudflare Tunnel.
One-Command Agent Skill & MCP Installer:
gflow skill installinstallsSKILL.mdfor Antigravity, Claude Code, Codex, and Cursor.gflow mcp installregistersgflow-mcpin your local IDE MCP config.
Related MCP server: google-flow-mcp
Installation
# Install CLI + Browser login/reCAPTCHA + MCP server via uv:
uv tool install --python 3.12 --editable ".[browser,mcp]"
# Ensure Playwright Chromium is installed once:
playwright install chromiumQuickstart
1. Authenticate with Google Flow
# Launch interactive browser login:
gflow login
# OR reuse an existing notebooklm-py Google login session instantly:
gflow login --from-notebooklm
# Verify authentication, live credits, and XSRF/reCAPTCHA bootstrap:
gflow doctor
gflow usage2. Manage Projects & Generate Assets via CLI
# List projects or create & activate a new one
gflow list
gflow create "Cyberpunk Short Film" --use
# Generate a Nano Banana Pro keyframe image
gflow generate image "Neon-lit rainy alley in Neo-Tokyo, anamorphic 35mm" --aspect 16:9 -o start.jpg
# Generate an 8s Veo 3.1 video starting from an image or media_id
gflow generate video "Camera dollies forward through steam as neon signs flicker" \
--model fast --start-frame start.jpg --wait -o shot1.mp4
# Extract the final frame at 7.8s to chain Shot 2 seamlessly
gflow frame-save <shot1_media_id> --at 7.8
# Start + End frame interpolation
gflow generate video "Smooth whip-pan transition from alley to rooftop skyline" \
--start-frame <frame_a_id> --end-frame <frame_b_id> --wait
# Upsample a clip to 1080p or 4K
gflow upsample <shot1_media_id> --target 1080p --wait -o shot1_1080p.mp4
# Assemble & export a multi-clip stitched MP4 in Scene Builder
gflow scene create "Main Cut" --aspect 16:9 --clip <shot1_media_id> --clip <shot2_media_id>
gflow scene trim <scene_id> 0 --start 0.5 --end 7.5
gflow scene export <scene_id> -o final_cut.mp4Every command supports --json for deterministic agent parsing.
Python SDK Usage
import asyncio
from gflow import FlowClient
async def main():
async with FlowClient.from_storage() as client:
credits = await client.get_credits()
print(f"Remaining Flow credits: {credits.total_credits}")
project = await client.create_project("SDK Demo")
images = await client.generate_image(
project.id,
"Minimalist sunlit ceramic studio, architectural photography",
model="pro",
aspect_ratio="16:9",
)
videos = await client.generate_video(
project.id,
"Slow orbital camera movement around the potter's wheel, natural morning light",
model="fast",
start_frame=images[0].id,
wait=True,
)
saved = await client.download_media(videos[0], "studio_shot.mp4")
print(f"Saved MP4 to {saved}")
asyncio.run(main())Agent Integration (Antigravity / Claude Code / claude.ai)
Install Agent Skill & Local stdio MCP
gflow skill install --target all
gflow mcp install --target antigravityExpose Remote HTTP MCP for claude.ai via Tailscale Funnel
gflow-mcp defaults to port 9421 so it can run side-by-side with notebooklm-mcp (9420). When running both on the same machine with Tailscale Funnel, expose gflow-mcp on Tailscale Funnel's secondary HTTPS port 8443:
# 1. Expose localhost:9421 on Tailscale Funnel HTTPS port 8443
/Applications/Tailscale.app/Contents/MacOS/Tailscale funnel --bg --https=8443 9421
# 2. Launch gflow-mcp with self-hosted single-password OAuth 2.1
export GFLOW_MCP_OAUTH_PASSWORD="$(openssl rand -base64 18)"
export GFLOW_MCP_OAUTH_BASE_URL="https://<your-device>.<tailnet>.ts.net:8443"
export GFLOW_MCP_ALLOW_EXTERNAL_BIND=1
gflow-mcp --transport http --host 127.0.0.1 --port 9421Then in claude.ai (or any remote MCP client) -> Settings -> Connectors -> Add custom connector:
Remote MCP Server URL:
https://<your-device>.<tailnet>.ts.net:8443/mcpAuthorize in the browser popup using your
GFLOW_MCP_OAUTH_PASSWORD.Direct Remote Image Upload (
P0-1): Remote VM agents can passimage_base64directly toflow_upload_image(up to 15 MiB decodedPNG/JPEG/WebP), orPUTraw binary bytes toflow_create_upload_link(up to 20 MiB /20,971,520bytes, 30m TTL) with zero human relay, receiving amedia_idforstart_frame_media_id/end_frame_media_id/reference_media_ids.Direct Remote Asset Retrieval (
P0-2): Generated images/videos and Scene Builder stitched MP4 exports (flow_scene_export_mp4) return 24-hour (86,400s) HMAC-signed HTTPSdownload_linkURLs withfile_size_bytes/sha256(X-GFlow-Bytes&X-GFlow-SHA256headers) for unauthenticated byte-exact VM downloads.Session Auto-Renewal (
P0-3), Timeout/Idempotency (P1-4), Structured Errors (P1-5), & Verified Limits (P2-6):9-minute
RotateCookieskeepalive + 3-rung session recovery; unrecoverable revocation fails fast withAUTH_EXPIRED.Soft-wait ceiling (
25sdefault,35smax) + shieldedjob_idpersistence + 7-dayidempotency_keydeduplication (never double-submits or double-charges Flow credits).Canonical JSON
error_codevalues:AUTH_EXPIRED,QUOTA_EXCEEDED,INVALID_INPUT,RATE_LIMITED,UPSTREAM_ERROR,NOT_FOUND.Full empirical limits & retention reference:
docs/MCP_CONNECTOR_LIMITS.md.
Development & Tests
pytest -qTool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Generate images and videos with Seedance, Veo, Wan, Grok, GPT-Image and Nano Banana via one MCP.
AI image, video, voice and music generation over MCP, routed to Veo 3.1, Seedance 2.5 and more.
OCR, transcription, file extraction, and image generation for AI agents via MCP.
Build, run, schedule, and publish AI video pipelines to YouTube and TikTok from any MCP client.
Related MCP Servers
- AlicenseBqualityDmaintenanceMCP server that lets AI agents control Google Flow for generating images and videos using the user's own Google account. It provides tools for image generation, video creation, character and scene management, and UI discovery.171MIT
- AlicenseAqualityBmaintenanceEnables AI agents to programmatically generate images and videos through the authenticated Google Flow web interface via a direct Chrome DevTools Protocol connection, exposing tools for media generation, project management, status checks, and asset downloads without requiring official API keys.276MIT
- AlicenseCqualityBmaintenanceEnables AI agents to orchestrate Google Flow video and image generation, including multi-scene planning, silent background generation, credit tracking, and video stitching via MCP.25MIT
- AlicenseCqualityCmaintenanceEnables Claude, Cursor, or any MCP client to create consistent AI characters, generate Veo 3.1 and Omni videos, edit clips, build scenes, export MP4s, and chat with Google Flow's creative agent. Automates AI video production workflows such as reels, storyboards, and multi-shot stories through natural language, with credit guardrails and dry-run pricing.2316MIT