film-subtitles-mcp

把影片或音檔轉成逐字稿與繁體中文字幕的 MCP server。

兩條路線：

轉錄用 Groq Whisper，翻譯／校對預設也走 Groq——只要一把免費的 Groq 金鑰就能全部跑完，不必另外安裝任何 CLI。

設計原則

• 翻譯後端永遠看不到時間軸，只拿到一串編號句子，回傳同樣數量的譯文。數量對不上就重試、再不行拆小批重試，絕不「少一句也沒關係」。

• 組回字幕時用的是逐字稿原本的時間軸；寫檔後再讀回來逐條比對，時間軸一個字元都不能變。

• 中途斷掉（網路、配額、關機）直接重跑，已完成的切片與翻譯批次會跳過。

Related MCP server: faster-whisper-mcp

需要什麼

1. uv（用來下載並執行這支 server）

   • Windows：winget install astral-sh.uv

   • macOS：brew install uv

   • 其他方式見 https://docs.astral.sh/uv/getting-started/installation/

2. ffmpeg / ffprobe

   • Windows：winget install Gyan.FFmpeg

   • macOS：brew install ffmpeg

   • 裝完重開終端機。

3. 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

工具

轉字幕是長時間工作（一小時影片約數分鐘），所以拆成 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