Skip to main content
Glama

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 (batchexecute JSPB 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), and media inspection.

    • 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 image media_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.

    • http with built-in Self-Hosted Single-Password OAuth 2.1, MultiAuth static bearer support, DNS-rebinding Host guard, and HMAC-signed /files/dl/{token} & /files/ul/{token} out-of-band media streaming & browser image upload links for claude.ai Custom Connectors over Tailscale Funnel or Cloudflare Tunnel.

  • One-Command Agent Skill & MCP Installer:

    • gflow skill install installs SKILL.md for Antigravity, Claude Code, Codex, and Cursor.

    • gflow mcp install registers gflow-mcp in 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 chromium

Quickstart

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 usage

2. 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.mp4

Every 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 antigravity

Expose 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 9421

Then in claude.ai (or any remote MCP client) -> Settings -> Connectors -> Add custom connector:

  • Remote MCP Server URL: https://<your-device>.<tailnet>.ts.net:8443/mcp

  • Authorize in the browser popup using your GFLOW_MCP_OAUTH_PASSWORD.

  • Direct Remote Image Upload (P0-1): Remote VM agents can pass image_base64 directly to flow_upload_image (up to 15 MiB decoded PNG/JPEG/WebP), or PUT raw binary bytes to flow_create_upload_link (up to 20 MiB / 20,971,520 bytes, 30m TTL) with zero human relay, receiving a media_id for start_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 HTTPS download_link URLs with file_size_bytes / sha256 (X-GFlow-Bytes & X-GFlow-SHA256 headers) 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 RotateCookies keepalive + 3-rung session recovery; unrecoverable revocation fails fast with AUTH_EXPIRED.

    • Soft-wait ceiling (25s default, 35s max) + shielded job_id persistence + 7-day idempotency_key deduplication (never double-submits or double-charges Flow credits).

    • Canonical JSON error_code values: 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 -q

Tool Schema Changelog

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

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers