caption-forge-mcp

Subtitles that your AI assistant can actually fix.

caption-forge-mcp is a Model Context Protocol server for working with captions: convert SRT ⇄ VTT ⇄ ASS, fix sync drift, lint for readability, and turn long subtitle lines or raw speech-to-text word timings into the short, punchy captions you see on Reels, TikTok and Shorts.

Pure TypeScript. No ffmpeg, no API keys, no network. Works on any caption file you point it at — or on caption text pasted straight into the chat.

You:    My podcast SRT is 1.2 seconds late and the lines are huge. Make reel captions,
        all caps, and give me an ASS file I can burn into the vertical cut.
Claude: Shifted -1200 ms, then reflowed 214 cues → 611 three-word captions.
        Saved ep42_reels.ass (1080x1920, bold, above the UI zone). Burn in with:
        ffmpeg -i ep42_vertical.mp4 -vf "subtitles='ep42_reels.ass'" -c:a copy out.mp4

Tools

Every tool accepts either path (a local file) or content (the caption text). Results come back inline unless you pass output_path.

Formats

Related MCP server: faster-whisper-mcp

Requirements

• Node.js 20+. That's it.

Install

Runs straight from GitHub with npx — nothing to publish or build.

Claude Desktop

Settings → Developer → Edit Config:

{
  "mcpServers": {
    "caption-forge": {
      "command": "npx",
      "args": ["-y", "github:anshumanofficial2002-cpu/caption-forge-mcp"]
    }
  }
}

Restart Claude Desktop.

Claude Code

claude mcp add caption-forge -- npx -y github:anshumanofficial2002-cpu/caption-forge-mcp

Cursor / Windsurf / VS Code / other clients

{
  "caption-forge": {
    "command": "npx",
    "args": ["-y", "github:anshumanofficial2002-cpu/caption-forge-mcp"]
  }
}

From source

git clone https://github.com/anshumanofficial2002-cpu/caption-forge-mcp.git
cd caption-forge-mcp && npm install && npm run build
# point your client at: node /absolute/path/to/caption-forge-mcp/dist/index.js

Example prompts

• "What's wrong with ~/Downloads/interview.srt? Lint it with the standard streaming rules."

• "These captions start in sync but are 3 seconds late by the end. Line 1 should be at 00:00:02,100 and the last line at 00:41:55,300."

• "Convert episode.vtt to SRT and remove the [MUSIC] tags."

• "Make TikTok-style captions from whisper_words.json, two words at a time, uppercase, as an ASS file for a vertical video."

• "I clipped 12:03 to 12:58 from the podcast. Give me captions for just that clip."

• "Find every time the guest says 'compounding' in ep12.srt."

• "Turn this SRT into a clean transcript with timestamps every paragraph, I need show notes." (paste the SRT)

Tool reference

Common input params for every caption tool:

convert_captions

to (required), ass_style:

shift_captions

offset — ms number or "2.5s", "-1500ms", "-00:00:01,200". from — only shift cues at/after this time.

retime_captions

mode: fps (from_fps, to_fps), factor (factor), or sync_points (first_original, first_correct, second_original, second_correct).

lint_captions

Override any rule: max_chars_per_line, max_lines, max_cps, min_duration_ms, max_duration_ms, min_gap_ms. Limit output with max_issues.

clean_captions

min_gap_ms (83), min_duration_ms (833), merge_duplicates (true), remove_hearing_impaired (false).

reflow_captions / captions_from_words

reflow_captions estimates word timing inside each original cue from word length. For exact timing, use captions_from_words with words_path or words_json. Accepted shapes:

[{ "word": "Hey", "start": 0.0, "end": 0.3 }]                 // seconds
[{ "text": "Hey", "start_ms": 0, "end_ms": 300 }]             // milliseconds
{ "segments": [{ "words": [{ "word": " Hey", "start": 0.0, "end": 0.3 }] }] }   // Whisper
{ "results": { "channels": [{ "alternatives": [{ "words": [...] }] }] } }        // Deepgram

clip_captions

start, end (source times), rezero (true).

search_captions

query, regex (false), whole_word (false), context (1), max_results (50).

extract_transcript

timestamps (false), paragraph_gap_ms (2000), strip_speaker_tags (false), output_path.

Notes

• ASS input loses its original styles when written back out; text and timing are kept.

• Reading speed (CPS) counts every visible character including spaces, the usual convention for subtitle guidelines.

• Overwrites are refused unless overwrite: true, and writing over the input file needs it explicitly.

Development

npm install
npm run build
npm test          # parser/ops unit tests + end-to-end tests over stdio
npm run inspect   # MCP Inspector

dist/ is committed so npx github:… works without a build; CI verifies it matches src/.

Related servers

• video-probe-mcp — inspect and conform video for each platform

• caption-forge-mcp — SRT/VTT/ASS conversion, timing, linting and reel-style captions

• loudness-check-mcp — LUFS, true peak, normalization, silence and clipping

• frame-grab-mcp — frames, contact sheets, scene cuts and thumbnails your AI can see

• script-timer-mcp — time, trim and format scripts for short-form video

License

MIT © 2026 Anshuman