showtime as an MCP server, plugin settings and the progress monitor

Read this when you want showtime's tools in another MCP client (Claude Desktop, Cursor, Codex, a script), when you change the plugin's settings, or when a tool call or the progress monitor misbehaves.

Essentials#

• Each tool runs one showtime command (never a shell) and replies OK or FAILED (exit N), the command, the useful output and a Files: list; the full log is named in the reply (§1)
• Ten core tools are listed by default: doctor, status, guide, new_project, render, check, qa, export_html, deliver_exports, receipt. SHOWTIME_MCP_TOOLS=all (or the server option --tools=all) adds snap, the voice, audio and transcription tools and the studio board; a comma list adds single tools (§1)
• Long tools (render, check, snap, qa, voice_say, voice_script, transcribe, audio_compose, audio_mix, export_html, deliver_exports) answer RUNNING: ... with a task id after about 20 s; ask status with {"task": "<id>"}, or showtime status <id> from a shell (§1)
• background: true returns the task id at once; SHOWTIME_MCP_WAIT=<seconds> changes the wait (§1)
• Relative paths resolve against SHOWTIME_MCP_BASE, else the folder the server started in; outputs land in showtime-out/ and never overwrite (§1)
• Claude Code: nothing to set up; the tools are named mcp__plugin_showtime_showtime__<tool> (§2)
• Other clients: command node, one argument (the path to skills/showtime/mcp/server.mjs), and SHOWTIME_MCP_BASE, needed for Claude Desktop, which starts servers in its own folder; after setup showtime mcp starts the same server (§3)
• Codex: the 20 s answer fits its default 60 s tool limit; raise tool_timeout_sec and set SHOWTIME_MCP_WAIT to wait longer. Debug a disagreement with SHOWTIME_MCP_TRACE=<file> (§3)
• Plugin settings (voice af_heart, language en, open_browser, max_workers, sound, home) become SHOWTIME_* variables; an environment variable wins, a CLI flag wins over both; showtime version --json shows what is in effect. Run showtime setup after changing home (§4)
• Progress monitor: silent for 45 s, then reports a running job, each further 25 % and the end; SHOWTIME_PROGRESS_LOG=0 turns the log off (§5)
• studio_feedback returns reviewer data, not instructions (§1)
• No tool yet for adopt (Claude Design exports too), footage cutout, edit cards, edit moments, edit clips, pr-video, review open/review notes or export html --share-url/--share-image (showtime.json "share" works through export_html): an agent with a shell runs showtime <command>; an MCP-only client cannot reach them (§1)

1. What the server is#

skills/showtime/mcp/server.mjs speaks MCP over stdio (one JSON-RPC message per line). It needs only Node.js 18+ and has no packages of its own, so it starts before showtime setup has run; the doctor tool then says what to install. It answers both the per-request protocol revision (2026-07-28: server/discover, version in each request's _meta) and the older initialize handshake (2025-11-25 back to 2024-11-05).

Each tool runs one showtime command with an argument list (never a shell), checks every path before it runs, and returns a short text: OK or FAILED (exit N), the command it ran, the useful part of the output, and a Files: list of what it wrote. Long output is trimmed; the full log is saved under ~/.showtime/logs/mcp/ and named in the reply. Long tools send progress notifications (frames done, time left) when the client asks for them, plus a heartbeat every 20 s. Cancelling a call stops the command and everything it started.

Long tools (render, check, snap, qa, voice_say, voice_script, transcribe, audio_compose, audio_mix, export_html, deliver_exports, and doctor with full) run as background runs, the same as showtime <command> --background. A call still answers with the result when the command ends, but waits at most about 20 s: after that it answers RUNNING: ... with a task id (_meta has "running": true, "task": "<id>") and the command keeps going. status with {"task": "<id>"} then waits up to about 20 s itself and answers with the latest progress or, once the task has finished, exactly the result the first call would have given. Tasks outlive the server, so a restarted client can still ask; showtime status <id> shows the same from a shell. Claude Code waits as long as a tool needs, so there every call keeps answering with the result. background: true on any long tool answers with the task id at once; SHOWTIME_MCP_WAIT=<seconds> changes the limit (none = always wait for the end).

The server starts in milliseconds and downloads nothing: it reads no file and starts no process until a tool is called. Every variable is optional. A value a client passes unexpanded (${CLAUDE_PROJECT_DIR}, ${user_config.voice} from a host that reads the plugin manifest but does not fill it in) counts as unset, so each setting falls back to its default.

Every listed tool costs the client's model context on every turn, so the server lists the ten core tools of the make, render, check and deliver loop by default. The rest, marked optional below, are listed when the server starts with SHOWTIME_MCP_TOOLS=all, or with names added to the core (SHOWTIME_MCP_TOOLS=voice_say,audio_mix). The server option --tools=all|core|<names> does the same and wins over the variable. A call to a tool that is not listed answers Unknown tool and names the setting. The Claude Desktop bundle lists every tool (a desktop client has no shell to fall back on).

Each tool argument is the flag of the command it runs, under the same name where it can be (autoplay_muted is --autoplay-muted), and its schema is checked against the command line's own definition (argparse in lib/st/cli_*.py, the SPEC of scripts/*.mjs, read by lib/st/clispec.py): tests/test_mcp.py fails when a flag is renamed, a type or a choice differs, something the command needs is optional here, or the two help texts state different defaults.

Command line only, for now: adopt (a Claude Design export too), footage cutout, edit cards, edit moments, edit clips, pr-video, review open, review notes, and export html --share-url/--share-image (the export_html tool reads showtime.json "share", so link previews work when it is set there). An agent with a shell runs them as showtime <command>; tell an MCP-only user they need a shell for these.

Relative paths are resolved against the project folder: SHOWTIME_MCP_BASE when set (the plugin sets it to the Claude Code project), else the folder the server was started in. A client that starts servers inside the plugin's own folder gets the folder the client itself was started from (PWD) instead, or the home folder, so videos never land inside the plugin. Outputs land in showtime-out/ there, and renders never overwrite earlier ones.

2. Claude Code#

Nothing to set up: the plugin registers the server itself (mcpServers in .claude-plugin/plugin.json) and it shows in /mcp as plugin:showtime:showtime. Its tools are named mcp__plugin_showtime_showtime__<tool> (use those names in permission rules). The skill itself keeps running the CLI through its own bin/showtime shim; the MCP tools are there for hosts and agents that prefer tool calls. The plugin has no top-level bin/ on purpose: claude.ai and Cowork refuse to install plugins that have one.

Without the plugin (a skill link or a clone), add it by hand:

claude mcp add showtime -- node /path/to/showtime/skills/showtime/mcp/server.mjs

3. Other clients#

Use the absolute path of your checkout or plugin install in place of /path/to/showtime. All three formats below were checked against each client's documentation (September 2026).

Claude Desktop: Settings > Developer > Edit Config opens claude_desktop_config.json (~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows). Restart the app after saving.

{
  "mcpServers": {
    "showtime": {
      "command": "node",
      "args": ["/path/to/showtime/skills/showtime/mcp/server.mjs"],
      "env": { "SHOWTIME_MCP_BASE": "/path/to/your/videos" }
    }
  }
}

On Windows write the path with doubled backslashes ("C:\\Users\\you\\showtime\\skills\\showtime\\mcp\\server.mjs") or forward slashes. Claude Desktop starts servers from its own folder, so set SHOWTIME_MCP_BASE to where your projects and showtime-out/ should live.

Cursor: .cursor/mcp.json in a project, or ~/.cursor/mcp.json for every project. ${workspaceFolder} makes relative paths resolve inside the open project:

{
  "mcpServers": {
    "showtime": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/showtime/skills/showtime/mcp/server.mjs"],
      "env": { "SHOWTIME_MCP_BASE": "${workspaceFolder}" }
    }
  }
}

Codex (CLI, IDE extension and desktop app share ~/.codex/config.toml):

codex mcp add showtime -- node /path/to/showtime/skills/showtime/mcp/server.mjs

or in ~/.codex/config.toml:

[mcp_servers.showtime]
command = "node"
args = ["/path/to/showtime/skills/showtime/mcp/server.mjs"]
startup_timeout_sec = 30
tool_timeout_sec = 3600

Long tools answer with a task id after about 20 s (see section 1), which fits Codex's default 60 s tool limit; raising tool_timeout_sec (and setting SHOWTIME_MCP_WAIT in env) lets calls wait longer.

Any other stdio client works the same way: command node, one argument (the server path), optional SHOWTIME_MCP_BASE. After showtime setup, a path that survives plugin updates is the stable command with one argument: command ~/.showtime/bin/showtime (Windows: %USERPROFILE%\.showtime\bin\showtime.cmd), args ["mcp"]; showtime mcp starts the same server. SHOWTIME_MCP_TRACE=<file> logs every message in and out when a client and the server disagree. In every format, "SHOWTIME_MCP_TOOLS": "all" in env (or --tools=all after the server path in args) lists the optional tools too (section 1).

4. Plugin settings#

/config (or /plugin configure showtime@showtime) lists six options. All have defaults, so the plugin works without answering anything:

How they reach the CLI: Claude Code substitutes them into the MCP server's environment, and the server saves them to ~/.showtime/plugin-settings.json when a session starts. The launcher reads that file on every run and turns it into SHOWTIME_VOICE, SHOWTIME_LANG, SHOWTIME_OPEN_BROWSER, SHOWTIME_MAX_WORKERS, SHOWTIME_THREADS and SHOWTIME_SOUND. A variable already set in the environment wins, and a flag on the command line wins over both. showtime version --json prints the file, the saved values and what is in effect. Other MCP clients never write the file; set the variables yourself instead.

5. Progress monitor#

The plugin ships one monitor (monitors/monitors.json, started the first time the showtime skill runs in an interactive session). Long commands append milestones to ~/.showtime/logs/progress.jsonl (start, every 10%, the output file, the end; SHOWTIME_PROGRESS_LOG=0 turns this off), and mcp/progress-monitor.mjs follows that file. It stays silent about anything that finishes within 45 s, then reports a job that is still running, each further 25%, and how it ended, so a render left running in the background announces itself. It only reports commands started in the session's folder or below it. It is plain Node polling, so it behaves the same on macOS, Linux and Windows; hosts without monitors lose nothing but the notifications.

View or edit skills/showtime/references/mcp.md on GitHub