gflow-cli

Name: gflow-cli
Author: Flavio Oliva

Generate Veo videos and Nano Banana or Imagen images through your own Google Flow account

By Flavio Oliva (individual) Python Local · stdio, Streamable HTTP Media AI and ML

GitHub PyPI Website

67 popularity score ★ 367 ↓ 6.9k/mo

Connect your client

Local (once it is running)

Add in one click

Add to Cursor Add to VS Code Add to LM Studio Add to Goose

Opens the app, which asks before it adds the server.

Or add it by command or config

Claude CodeTerminal

claude mcp add --transport http gflow-cli http://127.0.0.1:8000/mcp

Cursor~/.cursor/mcp.json

{
  "mcpServers": {
    "gflow-cli": {
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

VS Code.vscode/mcp.json

{
  "servers": {
    "gflow-cli": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

Codex~/.codex/config.toml

[mcp_servers.gflow-cli]
url = "http://127.0.0.1:8000/mcp"

Gemini CLITerminal

gemini mcp add --scope user --transport http gflow-cli http://127.0.0.1:8000/mcp

Local (PyPI)

Add in one click

Add to Cursor Add to VS Code Add to LM Studio

Opens the app, which asks before it adds the server.

Or add it by command or config

FirstTerminal

uv tool install gflow-cli
uv tool run --from gflow-cli playwright install chromium
gflow auth login --browser chrome

Claude CodeTerminal

claude mcp add gflow-cli -- gflow mcp run

Claude Desktopclaude_desktop_config.json

{
  "mcpServers": {
    "gflow-cli": {
      "command": "gflow",
      "args": [
        "mcp",
        "run"
      ]
    }
  }
}

Cursor~/.cursor/mcp.json

{
  "mcpServers": {
    "gflow-cli": {
      "command": "gflow",
      "args": [
        "mcp",
        "run"
      ]
    }
  }
}

VS Code.vscode/mcp.json

{
  "servers": {
    "gflow-cli": {
      "type": "stdio",
      "command": "gflow",
      "args": [
        "mcp",
        "run"
      ]
    }
  }
}

Codex~/.codex/config.toml

[mcp_servers.gflow-cli]
command = "gflow"
args = ["mcp", "run"]

Gemini CLITerminal

gemini mcp add --scope user gflow-cli gflow -- mcp run

Settings 6

`GFLOW_MCP_NO_SPEND`	Optional: Set to 1 to leave out the two credit-spending generate tools.
`GFLOW_CLI_OUTPUT_DIR`	Optional: Folder where generated files are saved.
`GFLOW_CLI_STORAGE_URI`	Optional: Send outputs to S3, MinIO or Google Cloud Storage instead of local disk.
`GFLOW_CLI_FLOW_HOST`	Optional: Which Flow frontend to drive (labs.google or flow.google.com).
`GFLOW_DAEMON_TOKEN`	Optional: Bearer token for `gflow serve`; needed when binding beyond loopback.
`GFLOW_CLI_LEASE_WAIT_SECONDS`	Optional: How long a call waits for a busy browser profile (180 s under MCP).

What it does

gflow-cli is a Python command-line tool for Google Flow that also runs as a local MCP server, started with `gflow mcp run` over stdio or `gflow serve` over Streamable HTTP. It has no API key route: it opens a persistent Playwright Chromium profile signed in to your Google account and works the Flow web app on your behalf, so every request runs as you and draws on your own Flow allowance.

Through the server an assistant can create images from text or from reference images (Nano Banana 2.1, 2 Lite, Pro or Imagen 4), create videos from text, a start frame or reference images with a choice of Veo model, duration and count, upscale finished images to 2K or 4K and videos to 1080p, fetch an already generated asset by media id, check the session and credit balance, list and inspect saved Flow characters, and manage a project's persistent Agent-Mode instruction cards. A local SQLite catalog records each generation, and outputs go to a local folder or to S3, MinIO or Google Cloud Storage.

The author marks it alpha, reverse-engineered and not affiliated with Google. At version 0.85.0 the server registers 18 tools in src/gflow_cli/mcp/tools.py, plus two prompts and resources for its docs and database schema. Generation calls pass through a token bucket of 8 calls refilled at one every 20 seconds, which the docs call the only spend brake: there is no credit budget or daily cap. Starting it with `--no-spend` or GFLOW_MCP_NO_SPEND=1 removes the two generate tools from the tool list altogether (server.py).

What it needs

Runtime	Python

Python with uv (`uv tool install gflow-cli`) or pip, then a one-time `playwright install chromium` download (about 150 MB). Google Chrome is recommended for sign-in. A Google account with Flow access, signed in once with `gflow auth login --browser chrome`, which opens a real browser window; a desktop session able to show a headed browser. Veo video generation spends the account's Flow credits; 4K image upscaling needs an Ultra plan (Pro allows 2K).

Limits

Alpha software built on Google's private Flow API and web UI, which can change without notice; when the UI drifts, runs stop with distinct exit codes (selector drift is exit 23). It needs a headed browser: there is no pure HTTP transport for video and no headless or serverless mode, and the published container image can only introspect, not generate. Accounts moved to flow.google.com support only part of the feature set; video upscaling works only there. Calls on one profile are serialized; under MCP a call waits up to 180 seconds for the profile lease (server.py). `gflow_list_projects` returns 50 rows per page by default. The Claude Code plugin tracks the develop branch, not a release.

Who it suits

Suits someone who already pays for Google Flow and wants an assistant to batch image and Veo video jobs, reuse characters or keep a project brief, on their own machine with a browser it can open. Because it signs in as you and automates Google's web app, it carries account risk under Google's terms and spends real credits on video; register it with `--no-spend` when the assistant should only look things up. Pick an official Gemini or Vertex AI API route instead for server-side, headless or team use, or where automating a consumer web app is not acceptable.

Tools 18

gflow_generate_image: Create images from a prompt, optionally with reference images or saved characters
gflow_generate_video: Create Veo videos from text, a start/end frame or references; spends credits
gflow_auth_status: Check whether the Flow session for a profile is still signed in
gflow_get_credits: Read the Flow credit balance for one or every saved profile
gflow_character_list: List a project's saved characters and their entity ids
gflow_character_show: Show one saved character by id or exact name
gflow_character_voices: List the preset voices available for character speech
gflow_list_projects: Page through recent generations in the local catalog
gflow_download_media: Download an already generated asset by its media id
gflow_upscale_image: Upscale a generated image to 2K or 4K
gflow_upscale_video: Upscale a video to 1080p, fetch the 720p original or export a GIF
gflow_list_tools: List the prompt-rewriting tools the generate tools accept
gflow_instructions_list: List a project's Agent-Mode instruction cards
gflow_instructions_add: Add an instruction card with optional image or character references
gflow_instructions_set_enabled: Turn one instruction card on or off
gflow_instructions_rm: Delete one instruction card
gflow_instructions_toggle_mode: Switch the whole instruction brief on or off
gflow_instructions_apply: Replace all of a project's instruction cards with a given set

Popularity

67 popularity score, on our list (the bar is 36)

★ 367 ↓ 6.9k/mo

GitHub stars	367	30.8 points
Stars in 30 days	+92	9.8 points
PyPI downloads, last month	6,947	25.9 points

Measured 2026-11-08. How the score works.

Where it is published

Code	ffroliva/gflow-cli ★ 367
PyPI	gflow-cli 0.96.0, 2026-11-07

What it can reach

Runs	On your machine
Reaches	Drives a browser, Your account at a service, The internet, Files on your machine
Changes things	Yes: it can write, send, create or delete
Sign-in	Account credentials
Licence	MIT (GitHub)
Last code change	2026-11-08

Runs on your machine with your user permissions and drives a Chromium profile holding your signed-in Google session; requests go to Google's private Flow endpoints as you. Not made by Google. Tools write generated media and a SQLite catalog to local disk (or to S3, MinIO or Google Cloud Storage if configured), spend Flow credits on video, and can add, change or replace a project's instruction cards (`gflow_instructions_apply` replaces all of them). The maker warns that automation is subject to Google's terms. `--no-spend` / GFLOW_MCP_NO_SPEND=1 unregisters both generate tools. `gflow serve` binds to 127.0.0.1 by default without a token; a non-loopback bind refuses to start unless GFLOW_DAEMON_TOKEN is set, and then every request needs it as a Bearer header.

Over time

GitHub stars 367 +92 (+33 %)

367275

10 Oct 20268 Nov 2026

PyPI downloads a month 6.9k +4.3k (+167 %)

7.3k2.5k

9 Jun 20267 Nov 2026

Before the site measured it, read from pypistats' daily download counts.

Popularity score 67 +11 (+21 %)

6755

10 Oct 20268 Nov 2026

What is rising across the directory

Sources

Page checked 2026-10-15.

Badge for your README

Shows this server's rank in its category, and stars for a server that runs on your machine. It updates every hour.

MarkdownREADME.md

[![gflow-cli on EveryMCPServer](https://everymcpserver.com/badge/gflow-cli.svg)](https://everymcpserver.com/servers/gflow-cli)

Connect your client

Add in one click

Or add it by command or config

Add in one click

Or add it by command or config

Settings 6

What it does

What it needs

Limits

Who it suits

Tools 18

Similar servers

flow-mcp

MeiGen AI Design MCP

comfyui-mcp

MCP Image Generator

Nano-Banana MCP Server

Nano Banana MCP Server