Skip to main content
Glama

English | Español

Flow Music MCP (flow-music-mcp)

A local Model Context Protocol (MCP) server that gives AI agents (Antigravity, Claude Code, OpenAI Codex, Claude Desktop, etc.) direct control over Google Flow Music using a dedicated, persistent Google Chrome profile.

Built for automated batch music production: let your agent read a video script, generate 8 custom soundtrack variations in the background, enforce credit budget caps, and download ready-to-edit MP3 / WAV / M4A / stems straight into your video project's folder without manual clicking.


Key Features

  • One-shot or batch background pipeline:

    • flow_music_create: generate, wait, and download a track in a single call.

    • flow_music_generate: queue up to 50 prompts/variations sequentially with human-like pacing.

  • Direct project output: save tracks straight into any local folder (output_dir) — such as your Remotion, Premiere, or CapCut project audio folder — or under ~/flow-music-mcp-out/<project>.

  • Built-in credit protection:

    • Reads your live credit balance before each run.

    • Supports max_credits_per_prompt and max_total_credits batch caps to automatically cancel remaining queued tracks before exceeding your budget.

    • Single-owner port lock (127.0.0.1:8788) prevents multiple AI clients from driving Chrome simultaneously and double-spending credits.

  • Full Compose controls: instrumental toggle, custom lyrics, sound description, optional title, BPM, length, seed, and model selection (Lyria 3.5 / Lyria 3 Pro).

  • Free library downloads: list your Flow Music library (flow_music_tracks) and download existing tracks as MP3, WAV, M4A, Stems (auto-extracted ZIP), or Video at zero credit cost.

  • Isolated from flow-mcp (video): uses a separate Chrome CDP port (9334) and separate browser profile (~/.flow-music-mcp/chrome-profile) so you can run video and music MCPs side by side without conflicts.


Related MCP server: Google Flow MCP

Requirements

  • Node.js 20+

  • Google Chrome installed on macOS, Windows, or Linux

  • A Google account with access to flowmusic.app


Quick Start (3 Steps)

1. Clone and build

git clone https://github.com/lifespring90/Flow_Music_MCP.git
cd Flow_Music_MCP
npm install
npm run build

2. Sign in once

Launch the dedicated Chrome profile and sign in with your Google account:

npm run login

Once https://www.flowmusic.app/ loads with your account signed in, your session stays saved in ~/.flow-music-mcp/chrome-profile. You can keep that Chrome window open or let the MCP server reopen it automatically whenever needed.

3. Add to your AI client

Replace /ABSOLUTE/PATH/TO/flow-music-mcp/dist/index.js with your actual path (for example /Users/you/flow-music-mcp/dist/index.js).

Antigravity

Add to ~/.gemini/antigravity/mcp_config.json (or via Manage MCP Servers in the Antigravity UI):

{
  "mcpServers": {
    "flow-music": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/flow-music-mcp/dist/index.js"]
    }
  }
}

Claude Code

claude mcp add flow-music -- node /ABSOLUTE/PATH/TO/flow-music-mcp/dist/index.js

Or in a project .mcp.json:

{
  "mcpServers": {
    "flow-music": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/flow-music-mcp/dist/index.js"]
    }
  }
}

OpenAI Codex

Add to ~/.codex/config.toml:

[mcp_servers.flow-music]
command = "node"
args = ["/ABSOLUTE/PATH/TO/flow-music-mcp/dist/index.js"]

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "flow-music": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/flow-music-mcp/dist/index.js"]
    }
  }
}

Available MCP Tools

Tool

Description

flow_music_status

Checks Chrome connection, login state, username, plan, credits remaining, and queue status.

flow_music_create

All-in-one: generates a track in Compose, waits for completion, measures credits spent, and downloads it locally.

flow_music_generate

Queues 1–50 prompts/variations in the background with pacing, output directory, and credit budget limits (max_total_credits, max_credits_per_prompt).

flow_music_wait

Waits for queued jobs or a task_id (~40 s chunks to avoid client timeouts) and returns downloaded file paths and credits spent.

flow_music_tracks

Lists tracks in your Flow Music library (id, title, duration, description, url).

flow_music_download

Downloads existing library tracks by UUID or title in mp3, wav, m4a, stems, or video (0 credits).

flow_music_cancel

Cancels a queued job before it starts.

flow_music_retry

Re-queues failed or cancelled jobs.

flow_music_outputs

Lists saved folders and audio files in ~/flow-music-mcp-out.


Example Agent Prompts

Single track in one command:

"Check flow_music_status, then generate an upbeat 120 BPM tropical funk instrumental for a product ad and save it as WAV in /path/to/my-video/audio."

Batch pipeline from a video script:

"Read script.md and use flow_music_generate to create 8 instrumental background music variations matching the mood of each scene. Save all MP3 files directly to /path/to/my-video/music, and set max_total_credits to 50."


Environment Variables (Optional)

Variable

Default

Purpose

FLOW_MUSIC_MCP_CDP_PORT

9334

Chrome remote debugging port (kept separate from flow-mcp's 9333).

FLOW_MUSIC_MCP_PORT

8788

Local coordinator lock port (kept separate from flow-mcp's 8787).

FLOW_MUSIC_MCP_HOME

~/.flow-music-mcp

Directory storing the Chrome profile, downloads cache, and lock token.

FLOW_MUSIC_MCP_OUTPUT

~/flow-music-mcp-out

Default output folder when using project instead of an absolute output_dir.

FLOW_MUSIC_MCP_PAUSE_MIN_S

15

Minimum seconds to pause between queued batch generations.

FLOW_MUSIC_MCP_PAUSE_MAX_S

35

Maximum seconds to pause between queued batch generations.

FLOW_MUSIC_MCP_CHROME

Auto-detected

Custom path to the Google Chrome executable.


Credits & Acknowledgments

Inspired by and adapted from the Chrome CDP + persistent-profile MCP architecture of GTAI-1/flow-mcp (video/image automation for Google Flow), redesigned cleanly from the ground up for Google Flow Music (flowmusic.app).


License

MIT

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

    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to programmatically generate images and videos through the authenticated Google Flow web interface via a direct Chrome DevTools Protocol connection, exposing tools for media generation, project management, status checks, and asset downloads without requiring official API keys.
      2
      7
      6
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Enables users to generate images and videos on Google Flow through browser automation of an already signed-in Chrome session, downloading the finished media to disk without any API keys. It drives Flow's agent with a range of image and video models, plus reference images, first/last frames, and ingredient-based video jobs, while reusing the user's own Google AI Pro credits.
      17
      MIT