Google Flow MCP (V2 Controller)

Self-hosted Model Context Protocol (MCP) server for Google Flow (labs.google/fx/tools/flow), refactored into a lean controller for book and story asset generation pipelines.

Authenticate with your own Google account to generate character candidates, props, places, scenes, and video clips—saving all outputs directly to your local file system or external drive (/Volumes/Xstorage/...).

---

Production Workflow Architecture

This MCP operates strictly as a controller for Google Flow asset creation:

Approved dossier
→ create book project
→ Storyboard Studio
→ characters / places / props / scenes
→ download candidates
→ approve stills
→ Veo / Omni animation
→ download clips
→ MiniMax
→ Remotion / CapCut

[!NOTE] This MCP server is a thin Google Flow controller layer. It does NOT handle full dossier truth systems, final trailer scripting strategy, MiniMax orchestration, Remotion assembly, CapCut rendering, or video publishing. Those operations belong outside this repository in the primary Immerse pipeline.

---

Key Principles & Scope

• 🎯 Google Flow Controller: Pure control layer for authenticating, listing/creating projects, executing Storyboard Studio/custom tools, generating media, and downloading assets locally.
• 🔒 Spend Guard & Budget Safety: Video generation tools (generate_video and generate_video_from_image) strictly require confirm_spend: true to prevent accidental credit consumption. Supports max_credits and max_generations limits.
• 📂 Local Storage Integration: Auto-scaffolds clean book folder structures (/characters, /props, /places, /scenes, /clips) on local or external drives.
• 🤝 Pipeline Handoff: Decoupled from final trailer editing or assembly. Assets are saved cleanly for handoff to external tools (MiniMax, Remotion, CapCut).
• 🔐 Isolated Auth & Safety: Session credentials are kept strictly isolated and stored locally with restricted 0600 file permissions.

---

Installation & Setup

1. Build Server

git clone https://github.com/LeoSzn12/google-flow-mcp.git
cd google-flow-mcp
npm install
npm run build

2. Environment Configuration

Copy .env.example to .env:

cp .env.example .env

Set your session credentials and local output root:

GOOGLE_COOKIES="your_google_cookies_string"
LOCAL_STORAGE_ROOT="/Volumes/Xstorage/Media"

---

Available MCP Tools (V2)

Core Control Tools (14)

Tool Name	Description	Key Parameters
flow_status	Check authentication state & account details	account
connect_google_account	Save Google auth cookies or tokens	cookies, bearerToken
list_projects	List Google Flow projects on your account	-
create_project	Create a new Google Flow project	name
list_tools	List custom tools in a project	project_id
run_custom_tool	Execute custom tool or Storyboard tool	tool_id, project_id, prompt, inputs
generate_image	Generate image via NARWHAL / Nano Banana	prompt, model, aspect, output_folder
generate_images_batch	Batch generate image candidates	prompts, model, aspect, output_folder
generate_video	Text-to-video via Veo 3.1 (Spend Guard)	prompt, confirm_spend (required), max_credits, max_generations, output_folder
generate_video_from_image	Image-to-video keyframe animation (Spend Guard)	prompt, start_image_url, confirm_spend (required), max_credits, max_generations, output_folder
check_job_status	Query status of async generation jobs	job_id, project_id
save_media_to_local_folder	Save generated media URL or ID to local disk	media_url_or_id, output_folder, filename
list_media	List all generated media items in session memory	-
get_media_details	Get details for a specific media item	media_id

Thin Helper Tools (2)

Tool Name	Description	Key Parameters
create_book_project	Scaffold local book folder structure on disk	book_title, local_storage_root
run_storyboard_studio_from_dossier	Execute Storyboard Studio with dossier input	dossier_text, book_title, asset_types, output_folder

---

Integration Guides

Claude Code / Codex

claude mcp add --transport stdio google-flow -- node /absolute/path/to/google-flow-mcp/dist/index.js

Cursor / Windsurf / Cline (mcpServers)

Add to ~/.cursor/mcp.json or .vscode/mcp.json:

{
  "mcpServers": {
    "google-flow": {
      "command": "node",
      "args": ["/absolute/path/to/google-flow-mcp/dist/index.js"],
      "env": {
        "GOOGLE_COOKIES": "your_google_cookies_string_here",
        "LOCAL_STORAGE_ROOT": "/Volumes/Xstorage/Media"
      }
    }
  }
}

---

Happy Path Example Workflow (The Odyssey)

Here is how to run a complete asset pipeline workflow for an example book (The Odyssey):

1. Create a Book Project & Local Storage Folders

Call create_book_project:

{
  "book_title": "The Odyssey",
  "local_storage_root": "/Volumes/Xstorage/Media"
}

Creates /Volumes/Xstorage/Media/the-odyssey/ with subfolders: characters/, props/, places/, scenes/, clips/.

2. Run Storyboard Studio with an Approved Dossier

Call run_storyboard_studio_from_dossier:

{
  "book_title": "The Odyssey",
  "dossier_text": "Odysseus: Weathered ancient Greek king and mariner, dark curly hair, bearded, wearing bronze-trimmed linen tunic, standing on rocky shore looking out at Aegean Sea.",
  "asset_types": ["characters", "places", "scenes"],
  "output_folder": "/Volumes/Xstorage/Media"
}

Generates visual candidates and downloads stills directly into local project subfolders.

3. Animate Approved Keyframes into Video Clips

Call generate_video_from_image with explicit spend authorization:

{
  "prompt": "Slow panning shot across Aegean sea waves crashing on rocky cliffs behind Odysseus",
  "start_image_url": "/Volumes/Xstorage/Media/the-odyssey/characters/odysseus_still.png",
  "confirm_spend": true,
  "max_credits": 20,
  "max_generations": 1,
  "output_folder": "/Volumes/Xstorage/Media/the-odyssey/clips"
}

Renders video using Google Veo 3.1 and saves flow_video_<timestamp>.mp4 to /clips.

4. Immerse Production Handoff

Hand off downloaded .png stills and .mp4 video clips to external assembly tools (MiniMax, Remotion, CapCut).

---

License

MIT