flow-mcp 0.3.0

Google Flow image generation as an MCP tool for Claude Code

Google Flow MCP 🎨

MCP server for generating images via Google Flow — no daily quota limits.

Claude Code (or any MCP client) can generate images using Google Flow's batchGenerateImages API directly through a Playwright browser context with your saved authentication, bypassing the Flow Agent chat quota (~10 images/day).

Features

• Text-to-Image — generate images from text prompts
• Image-to-Image — use a reference image (pass reference_image)
• No quota limits — calls the API directly, not through the chat
• Persistent browser pool — reuses Chrome across generations (faster)
• Auto-retry — refreshes auth token if it expires
• Progress reporting — shows generation progress in Claude Code
• No external CLI dependencies — includes its own auth/login
• Cross-platform — Windows, macOS, Linux (incl. headless)

Requirements

Dependency	Notes
Python 3.11+ (or uv)
Google Chrome or Playwright's Chromium	For authentication & generation
Xvfb (Linux headless only)	For auth login only (MCP server runs headless)

Installation

Prerequisites

• Python 3.11+
• Google Chrome (for authentication)
• Playwright browsers (for generation)

Install from PyPI (recommended)

pip install flow-mcp

# Or with uv:
# uv pip install flow-mcp

# Install Playwright browsers
playwright install chromium

# Authenticate with Google Flow
flow-mcp auth login

Or install from GitHub

git clone https://github.com/alarconcesar/flow-mcp.git
cd flow-mcp
uv pip install -e .
playwright install chromium
flow-mcp auth login

Usage with Claude Code

Add to your .claude/settings.json:

{
  "mcpServers": {
    "flow-image-server": {
      "command": "uv",
      "args": ["run", "flow-mcp"]
    }
  }
}

Restart Claude Code. The generate_image tool will be available.

Parameters

Parameter	Type	Default	Description
prompt	string	required	Text description of the image
model	enum	nano-pro	nano2, nano-pro, narwhal, gem_pix_2
count	integer	1	Number of images (1–4)
aspect	enum	9:16	9:16, 16:9, 1:1, 4:3, 3:4
reference_image	string	optional	Path to a local image for I2I

Examples

Text-to-Image:

Generate an image of a cyberpunk city at night, neon lights, 16:9

Image-to-Image:

Take this photo and make it cyberpunk style,
reference_image: /Users/me/photo.jpg

CLI commands

flow-mcp                    # Start MCP server (stdio mode)
flow-mcp auth login         # Authenticate with Google Flow
flow-mcp auth list          # List saved profiles
flow-mcp help               # Show help

Environment variables

Variable	Default	Description
GFLOW_PROFILE	auto-detected	Profile name
GFLOW_CLI_HOME	platform default	gflow-cli data directory
GFLOW_OUTPUT_DIR	temp directory	Where to save generated images

Troubleshooting

Auth expired

flow-mcp auth login

Content filter

Google Flow silently blocks certain prompts (returns None). Try rephrasing — avoid violence, NSFW, or trademarked content.

Linux headless

# Only needed for authentication (the MCP server itself runs headless)
Xvfb :99 -screen 0 1280x720x24 &
DISPLAY=:99 flow-mcp auth login --browser internal

The MCP server (flow-mcp) now runs completely headless — no Xvfb needed for generation.

Profile not found

flow-mcp auth list         # list profiles
flow-mcp auth login        # create a new profile

Project structure

flow-mcp/
├── src/
│   └── flow_mcp/
│       ├── __init__.py      # Package metadata & logging config
│       ├── __main__.py      # CLI entry point (auth, server)
│       ├── server.py        # FastMCP tool definition
│       ├── generator.py     # Core generation logic
│       ├── browser.py       # Playwright context & token capture
│       ├── browser_pool.py  # Persistent browser context pool
│       ├── auth.py          # Login, profile list commands
│       ├── profile.py       # Profile resolution
│       ├── recaptcha.py     # reCAPTCHA token minting
│       ├── chrome_helpers.py # Chrome detection
│       └── constants.py     # Shared constants
├── pyproject.toml
├── LICENSE (MIT)
└── README.md

License

MIT — see LICENSE.