film-subtitles-mcp
This server turns video or audio files into transcripts and Traditional Chinese subtitles using Groq Whisper, all through four MCP tools.
Transcribe English audio/video into an English
.en.srttranscript plus a.zh-TW.srtTraditional Chinese subtitle file (long lines split at punctuation).Transcribe Chinese audio into
.zh.srt(raw transcription) and.zh-TW.srt(converted to Taiwan Traditional, typos/punctuation corrected, long sentences split).Produce transcript-only output by setting
translate=false.Batch process multiple files or a whole folder (
.mp3 .m4a .wav .aac .flac .ogg .opus .wmaand common video formats).Run long jobs in the background:
transcribe_startreturns ajob_idimmediately, then polltranscribe_statusfor progress, output paths, and recent logs.List recent jobs with
transcribe_list.Improve proper-noun consistency by passing a
contextstring (e.g. "Revit, Dynamo, MCP").Choose a translation backend: default
groq, or any CLI agent supporting-p <prompt> --model <model>(e.g.agy,claude), with a selectablemodel.Verify the environment (ffmpeg, Groq key, translation backend) with
check_setup.Force redo existing subtitles with
force=true; interrupted jobs resume from where they stopped.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@film-subtitles-mcp add Traditional Chinese subtitles to this English video, proper nouns: Revit, Dynamo"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
film-subtitles-mcp
把影片或音檔轉成逐字稿與繁體中文字幕的 MCP server。
兩條路線:
音源 | 參數 | 產出 |
英文 |
|
|
中文 |
|
|
轉錄用 Groq Whisper,翻譯/校對預設也走 Groq——只要一把免費的 Groq 金鑰就能全部跑完,不必另外安裝任何 CLI。
設計原則
翻譯後端永遠看不到時間軸,只拿到一串編號句子,回傳同樣數量的譯文。數量對不上就重試、再不行拆小批重試,絕不「少一句也沒關係」。
組回字幕時用的是逐字稿原本的時間軸;寫檔後再讀回來逐條比對,時間軸一個字元都不能變。
中途斷掉(網路、配額、關機)直接重跑,已完成的切片與翻譯批次會跳過。
Related MCP server: faster-whisper-mcp
需要什麼
uv(用來下載並執行這支 server)
Windows:
winget install astral-sh.uvmacOS:
brew install uv其他方式見 https://docs.astral.sh/uv/getting-started/installation/
ffmpeg / ffprobe
Windows:
winget install Gyan.FFmpegmacOS:
brew install ffmpeg裝完重開終端機。
Groq 金鑰(免費):到 https://console.groq.com/keys 申請,等一下填進設定檔。
裝好之後可以先叫 check_setup 這支 tool 自我檢查。
安裝
不用 clone,直接讓 uvx 跑。
Claude Code:在終端機跑一行(-s user 表示所有專案都能用):
claude mcp add -s user film-subtitles -e GROQ_API_KEY=把你自己的金鑰貼在這裡 -- uvx --from git+https://github.com/s9101800111-byte/film-subtitles-mcp@v0.1.1 film-subtitles-mcp跑完用 claude mcp get film-subtitles 確認顯示 Connected。
Claude Desktop:把下面這段加進設定檔(Windows:%APPDATA%\Claude\claude_desktop_config.json;macOS:~/Library/Application Support/Claude/claude_desktop_config.json),存檔後完全結束 Claude 再重開:
{
"mcpServers": {
"film-subtitles": {
"command": "uvx",
"args": ["--from", "git+https://github.com/s9101800111-byte/film-subtitles-mcp@v0.1.1", "film-subtitles-mcp"],
"env": { "GROQ_API_KEY": "把你自己的金鑰貼在這裡" }
}
}
}
@v0.1.1是版本標籤,建議釘住。不釘版本的話上游一更新就可能整支掛掉。
剛裝完 uv 就設定的話,Claude 可能還找不到
uvx(連線失敗、ENOENT)。先完全結束 Claude 再重開;還是不行就把"command"改成 uvx 的完整路徑——在終端機跑where uvx(Windows)或which uvx(macOS)查,JSON 裡的反斜線要寫成\\。
要改程式碼就照一般方式 clone 下來:
git clone https://github.com/s9101800111-byte/film-subtitles-mcp
cd film-subtitles-mcp
uv sync
uv run film-subtitles-mcp工具
Tool | 用途 |
| 開始轉字幕,立刻回傳 |
| 查進度、產出的字幕檔路徑、最近的執行訊息 |
| 列出最近的工作 |
| 檢查 ffmpeg 與金鑰是否齊備 |
轉字幕是長時間工作(一小時影片約數分鐘),所以拆成 start/status 兩段,不會卡住對話。
用起來像這樣
「把
D:\錄音\會議.m4a轉成逐字稿」 「這支英文影片上中文字幕,專有名詞有 Revit 和 Dynamo」
context 參數填上專有名詞(例如 "Revit, Dynamo, MCP")能讓譯名穩定很多。
常見問題
「整部影片沒有轉出任何語音」 — 檔案真的沒有聲音,或截到了靜音片段。用 ffmpeg -i 檔案 -af volumedetect -f null - 確認。
音檔可以直接丟資料夾嗎? 可以。.mp3 .m4a .wav .aac .flac .ogg .opus .wma 與常見影片格式都會被掃到。
免費額度會卡嗎? Groq 免費層有每分鐘 token 限制,長片翻譯時可能遇到 429。程式會自己等待重試,重跑也會從中斷處接續。
想換翻譯模型? model 參數可填任何 Groq 上的模型,例如 qwen/qwen3.8-27b。預設是 openai/gpt-oss-120b(指令遵循最穩,這條 pipeline 最吃這個)。
想用自己的 CLI agent 翻譯? translator 填那支指令的名字(需支援 -p <prompt> --model <model>),例如 agy、claude。model 要一起指定該 CLI 認得的模型名(例如 claude 配 sonnet),留空會帶入 agy 的預設模型而失敗。該 CLI 也要事先在本機登入好。
授權
MIT
Available Tools
4 toolscheck_setupA
檢查這台電腦的環境是否齊備(ffmpeg、Groq 金鑰、翻譯後端)。裝完先跑這個。
Inputs: no named parameters.
transcribe_listC
列出最近的轉字幕工作與各自狀態。
Inputs: limit. Returns: result
transcribe_startA
把影片或音檔轉成字幕/逐字稿(開背景工作,立刻回傳 job_id)。
用在:影片上字幕、音檔轉文字、錄音轉逐字稿、演講/會議/課程影片轉文字、翻譯成中文字幕。
參數:
paths -- 影片或音檔的完整路徑,可給多個;也可以給整個資料夾。
language -- 音源語言。"en"=英文(產生英文逐字稿再翻成繁中字幕);
"zh"=中文(直接產生繁中字幕,會轉台灣繁體並校對錯字標點)。
translate -- True=要中文字幕;False=只要原文逐字稿。
translator -- "groq"(預設,只要 Groq 金鑰)或任何吃 -p/--model 的 CLI agent(例如 "agy")。
model -- 翻譯模型,留空用預設。
context -- 本片的專有名詞或背景,例如 "Revit, Dynamo, MCP",會讓譯名穩定。
force -- 字幕已存在也重做。
產出會放在原檔案旁邊:<檔名>.en.srt(或 .zh.srt)與 <檔名>.zh-TW.srt。 回傳 job_id,用 transcribe_status 查進度。
Inputs: paths (required), force, model, context, +3 more.
transcribe_statusB
查某支轉字幕工作的進度、產出的字幕檔路徑,以及最近的執行訊息。
Inputs: job_id (required), log_lines.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool clearly targets a distinct operation: transcribe_start creates a job, transcribe_status queries one job, transcribe_list lists all recent jobs, and check_setup validates the environment. There is no overlap or ambiguity in purpose.
All tool names use consistent snake_case with a predictable verb_noun structure (transcribe_list, transcribe_start, transcribe_status, check_setup). The shared transcribe_ prefix for core operations and distinct check_setup for setup are logically organized.
Four tools is well-scoped for a focused background transcription service: one for environment check, one to start jobs, one to list jobs, and one to check status. No unnecessary tools and no obvious thinness for the core workflow.
The core lifecycle (setup check, start job, list jobs, poll status) is fully covered. Minor gaps exist, such as cancelling/deleting jobs or directly retrieving subtitle content via MCP, but agents can work around these by using returned file paths.
Maintenance
Related MCP Connectors
Transcribes audio and video files to text, SRT, VTT and timestamped chunks for RAG.
Transcribe audio and video and work with your transcript library from any AI app. 119 languages.
Transcribe audio and video files to text with timestamps and SRT or WebVTT subtitles
Whisper speech to text for podcast, audio and video URLs, 90+ languages, timestamped output.
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceEnables high-performance audio transcription using Faster Whisper with CUDA acceleration, supporting single and batch audio file processing with multiple output formats (VTT, SRT, JSON).-
- FlicenseAqualityDmaintenanceEnables high-quality transcription and subtitle generation from local media files or URLs using Faster Whisper on local hardware. It supports automatic language detection and integration with MCP clients for seamless speech-to-text workflows.31-
- AlicenseAqualityDmaintenanceAutomatically transcribes Google Chat voice messages using Groq Whisper API, and also supports local audio file transcription.224 PyPIMIT
- AlicenseAqualityCmaintenanceProvides local audio transcription using whisper.cpp, supporting multiple models and audio formats. Enables transcription of audio files via MCP tools with optional timestamps.395 npm4MIT