# 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:

```text
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

```bash
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`:

```bash
cp .env.example .env
```

Set your session credentials and local output root:

```env
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

```bash
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`:

```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`:
```json
{
  "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`:
```json
{
  "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:
```json
{
  "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