FlowCast is an MCP server that renders a single, self-contained interactive HTML walkthrough from a timeline your agent authors. Code types itself out in a real editor, narration plays in sync, the camera follows the action — and the whole thing is one file you can open in any browser. No server. No build. No dependencies.

Ask Claude (or any MCP client) "walk me through the auth flow" and you get back a polished, scrubbable explainer instead of a wall of text.

The command is always the same — npx fetches and runs it locally over stdio, no global install:

command: npx     args: -y @flowcast/mcp@latest

See Add it to your agent for Claude Code, Claude Desktop, Codex, Cursor, Kiro, Windsurf, VS Code, and Gemini CLI.

Required: every cast is narrated, so FlowCast needs a text-to-speech key — bring your own OpenAI, ElevenLabs, or Google key (see Voice). The software is free; you only pay your TTS provider for the audio it generates.

New here? Run npx -y @flowcast/mcp setup — a one-time wizard that asks for your provider + key, validates it, saves it to ~/.flowcast/config.json, and offers to register FlowCast into the clients it detects (Claude Code, Claude Desktop, Cursor, Codex, Kiro, Windsurf, Gemini CLI, VS Code). No JSON editing required.

Add it to your agent

Most clients share one JSON config; a couple use their own format. Pick yours.

CLI shortcuts

# Claude Code
claude mcp add flowcast -- npx -y @flowcast/mcp@latest        # add -s user to enable it everywhere

# OpenAI Codex                                             # writes ~/.codex/config.toml
codex mcp add flowcast -- npx -y @flowcast/mcp@latest

# Kiro
kiro-cli mcp add --name flowcast --command npx --args "-y" --args "@flowcast/mcp@latest" --scope workspace

# VS Code
code --add-mcp '{"name":"flowcast","command":"npx","args":["-y","@flowcast/mcp@latest"]}'

A TTS key is required — pass it with --env. Claude Code: claude mcp add flowcast --env VOICE_MODEL=openai --env OPENAI_API_KEY=sk-... -- npx -y @flowcast/mcp@latest. Codex and Kiro take the same repeated --env KEY=VALUE flags.

Standard config (most clients)

Drop this into your client's MCP config file (the env key holds your required TTS key — swap in your provider):

{
  "mcpServers": {
    "flowcast": {
      "command": "npx",
      "args": ["-y", "@flowcast/mcp@latest"],
      "env": { "VOICE_MODEL": "openai", "OPENAI_API_KEY": "sk-..." }
    }
  }
}

| Client | Config file | |---|---| | Claude Desktop | claude_desktop_config.json — Settings → Developer → Edit Config | | Cursor | .cursor/mcp.json (project) or ~/.cursor/mcp.json (global) | | Kiro | .kiro/settings/mcp.json (workspace) or ~/.kiro/settings/mcp.json (user) | | Windsurf | ~/.codeium/windsurf/mcp_config.json | | Gemini CLI | ~/.gemini/settings.json |

Different formats

OpenAI Codex — ~/.codex/config.toml (TOML; note the underscore in mcp_servers):

[mcp_servers.flowcast]
command = "npx"
args = ["-y", "@flowcast/mcp@latest"]

VS Code — .vscode/mcp.json uses a servers key (not mcpServers):

{
  "servers": {
    "flowcast": {
      "command": "npx",
      "args": ["-y", "@flowcast/mcp@latest"],
      "env": { "VOICE_MODEL": "openai", "OPENAI_API_KEY": "sk-..." }
    }
  }
}

Your TTS key goes under env on the server entry (Codex TOML: env = { VOICE_MODEL = "openai", OPENAI_API_KEY = "sk-..." }). It's required — see Voice and Configuration.

Why it's different

• One file, fully interactive. Scrub, pause, and play like a video — but it's live code in a real CodeMirror editor, not a screen recording. Opens offline, in any browser.
• Your model does the thinking; FlowCast does the rendering. It runs no LLM of its own — your agent authors the timeline, this server turns it into a deterministic, pixel-stable cast.
• Four kinds of story. Code, whiteboard, map, and 3D — one consistent player.
• Always narrated. Every cast is voiced in sync (with matching captions) — you bring a TTS key.
• Runs locally. Rendering happens on your machine; your code never leaves it — only the short narration lines go to your chosen TTS provider.

Try it

In any codebase, just ask:

"Make an interactive walkthrough of the rate-limiter in src/middleware/." "Diagram how a request flows through the system as a whiteboard cast." "Give me a 3D walkthrough of our Q3 revenue numbers."

Your agent calls the matching tool and hands you a link to open.

What it can make

| Tool | Produces | |------|----------| | create_walkthrough | Code — files that type out in a live editor, synced narration, precise line highlights, and a terminal panel | | create_whiteboard_walkthrough | Whiteboard — animated concept maps and diagrams that draw themselves | | create_map_walkthrough | Map — narrated tours over an interactive geographic map | | create_3d_walkthrough | 3D — 3D scenes and data stories (e.g. animated charts) |

Plus three helpers your agent uses to ship a clean result:

| Tool | Does | |------|------| | check_walkthrough | Lints a draft for quality issues (ambiguous highlights, over-long narration, …) — read-only | | revise_walkthrough | Applies targeted fixes to a draft without re-authoring the whole timeline | | export_walkthrough | Writes the finished .html to a path you choose |

How you get the result

Every cast is returned three ways, so it works in any client:

1. A local preview URL — http://127.0.0.1:7616/<id>.html (loopback only). The most reliable way to view it with full interactivity.
2. A self-contained .html file — handed back as a file:// link; open or share it.
3. An MCP resource — ui://flowcast/<id>, fetchable by resource-aware hosts.

Voice

Voice is required — every cast is narrated, and synced captions are always shown alongside it. Pick a provider with VOICE_MODEL and set that provider's key (bring your own). Without a configured key, cast generation fails with a clear error — there is no silent captions-only fallback.

The easiest way to configure it is the one-time wizard:

npx -y @flowcast/mcp setup

It asks for your provider + key, validates it, saves ~/.flowcast/config.json (owner-only), and then offers to add FlowCast to each MCP client it finds — Claude Code, Codex, and VS Code via their own mcp add / --add-mcp command, and Claude Desktop / Cursor / Kiro / Windsurf / Gemini CLI by merging into their config (your existing file is backed up to .bak first, and every change is confirmed). The server reads the saved key automatically, so the registered entries hold no secrets. Prefer env? A key in your client's env block always overrides the saved file.

| VOICE_MODEL | Key | Default | |---|---|---| | openai (default) | OPENAI_API_KEY | gpt-4o-mini-tts | | elevenlabs | ELEVENLABS_API_KEY | eleven_turbo_v2_5, voice ELEVENLABS_VOICE_ID | | google | GOOGLE_TTS_API_KEY | voice GOOGLE_TTS_VOICE (e.g. en-US-Neural2-D) |

"flowcast": {
  "command": "npx", "args": ["-y", "@flowcast/mcp@latest"],
  "env": { "VOICE_MODEL": "elevenlabs", "ELEVENLABS_API_KEY": "..." }
}

Configuration

A TTS provider key is required; everything else is optional.

| Variable | Purpose | |---|---| | VOICE_MODEL | TTS provider: openai (default), elevenlabs, google | | OPENAI_API_KEY / ELEVENLABS_API_KEY / GOOGLE_TTS_API_KEY | Required — the key for your chosen provider | | FLOWCAST_CONFIG_DIR | Where the saved config lives (default ~/.flowcast) | | FLOWCAST_OUTPUT_DIR | Where .html files are written | | FLOWCAST_PORT | Local preview port (default 7616; next free port if taken) | | FLOWCAST_NO_HTTP | Set to 1 to disable the local preview server | | FLOWCAST_TTS_VOICE / FLOWCAST_TTS_MODEL / FLOWCAST_TTS_INSTRUCTIONS | Fine-tune the OpenAI voice |

Requirements

• Node.js ≥ 18 (npx handles the rest).
• A TTS provider key — OpenAI, ElevenLabs, or Google (see Voice). Required.
• An MCP client — Claude Desktop, Claude Code, Cursor, or any other.

License

Free to use — not open source. See LICENSE and THIRD-PARTY-NOTICES.