funasr-zh-tw-mcp

把阿里巴巴開源的 FunASR 中文語音辨識包成 MCP server、HTTP API 與 命令列工具，輸出**繁體中文（台灣用詞）**逐字稿。

全程在自己的電腦上運算，音檔不會上傳到任何雲端服務 —— 適合處理課堂錄音、會議記錄、訪談等不方便外傳的內容。

---

這個工具解決什麼問題

FunASR 的中文辨識品質很好，但預設輸出是簡體中文，而且只能寫 Python 腳本呼叫。這個專案做三件事：

1. 自動轉繁體 —— 使用 OpenCC s2twp 設定，連台灣慣用詞一起轉（軟件→軟體、網絡→網路、信息→資訊）
2. 包成 MCP server —— 讓 Claude、Gemini CLI、Cursor 等 AI 助理可以直接呼叫
3. 包成 HTTP API —— 讓自己的網頁工具或 ChatGPT 自訂 GPT 可以串接

---

支援哪些 AI 助理

平台	支援	說明
Claude Code	✅	claude mcp add 一行指令掛上
Claude Desktop	✅	編輯設定檔即可
Gemini CLI	✅	支援 MCP，設定方式類似
Cursor / Windsurf / Zed	✅	都支援 MCP
ChatGPT 桌面版	⚠️	開發者模式可掛 MCP，功能仍在演進中
ChatGPT 網頁版（自訂 GPT）	⚠️	需先用 ngrok / cloudflared 把 HTTP API 公開到網際網路，ChatGPT 的伺服器連不到你的 localhost
Gemini 網頁版 / Claude.ai 網頁版	❌	網頁版無法呼叫你本機的程式，這是瀏覽器沙箱的限制，不是設定問題

關於 Artifacts：Claude 的 Artifacts 有嚴格的 CSP 限制，禁止所有對外網路請求（包含 localhost），因此無法用 Artifact 呼叫本機的辨識服務。這是平台的安全設計，沒有繞過的方法。

---

安裝

1. 先裝 PyTorch

FunASR 需要 PyTorch，但它不會自動幫你裝（因為要看你有沒有顯卡）。

只用 CPU（大部分人）：

pip install torch torchaudio --index-url https://download.pytorch.org/whl/cpu

有 NVIDIA 顯卡（速度快很多）：

pip install torch torchaudio --index-url https://download.pytorch.org/whl/cu121

2. 裝本專案

pip install git+https://github.com/draiagent/funasr-zh-tw-mcp.git

要用 HTTP API 的話，加裝 api 選配依賴：

pip install "funasr-zh-tw-mcp[api] @ git+https://github.com/draiagent/funasr-zh-tw-mcp.git"

套件名稱是 funasr-zh-tw-mcp，但程式裡的模組名稱是 funasr_mcp（比較短好打）， 所以指令會寫成 python -m funasr_mcp.mcp_server。

3. 首次執行會下載模型

第一次辨識時會自動從 ModelScope 下載約 1.5GB 的模型權重（辨識模型 + 語音端點偵測 + 標點還原），存在 ~/.cache/modelscope。之後就不會再下載。

依網速不同可能需要 10–30 分鐘，請耐心等候。

---

用法一：命令列

funasr-transcribe 課堂錄音.m4a

輸出到檔案：

funasr-transcribe 課堂錄音.m4a -o 逐字稿.txt

其他選項：

參數	說明
-o, --output	輸出檔路徑
--simplified	不轉繁體，輸出模型原始簡體結果
--timestamps	附上每個字的時間戳（毫秒）

支援格式：wav mp3 m4a flac ogg opus aac wma mp4 mov webm

---

用法二：MCP server（給 AI 助理呼叫）

Claude Code

claude mcp add funasr -- python -m funasr_mcp.mcp_server

Claude Desktop

編輯設定檔：

• Windows：%APPDATA%\Claude\claude_desktop_config.json
• macOS：~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "funasr": {
      "command": "python",
      "args": ["-m", "funasr_mcp.mcp_server"]
    }
  }
}

如果你把套件裝在虛擬環境裡，command 要指向該環境的 python，例如 C:\\path\\to\\.venv\\Scripts\\python.exe。

設定完重開 Claude Desktop，就可以直接說：

幫我把 D:\錄音\第三堂課.m4a 轉成逐字稿

提供的工具

工具	功能
transcribe_audio	把音檔轉成繁體中文逐字稿。可選擇是否附時間戳。
preload_model	預先載入模型，讓下一次辨識可以立刻開始（首次載入約 40 秒）。

---

用法三：HTTP API

funasr-api

預設監聽 http://127.0.0.1:8000。

端點	方法	說明
/health	GET	服務狀態、模型是否已載入
/transcribe	POST	上傳音檔（multipart），回傳逐字稿
/docs	GET	互動式 API 文件
/openapi.json	GET	OpenAPI schema（ChatGPT Actions 需要）

範例：

curl -X POST http://127.0.0.1:8000/transcribe \
  -F "file=@課堂錄音.m4a" \
  -F "traditional=true"

從自己的網頁工具呼叫：

const form = new FormData();
form.append('file', audioFile);
const res = await fetch('http://127.0.0.1:8000/transcribe', {
  method: 'POST',
  body: form,
});
const { text } = await res.json();

環境變數

變數	預設	說明
FUNASR_API_HOST	127.0.0.1	監聽位址
FUNASR_API_PORT	8000	監聽埠號
FUNASR_API_TOKEN	無	設定後啟用 Bearer token 驗證
FUNASR_CORS_ORIGINS	僅 localhost	允許的跨來源網址，逗號分隔

接到 ChatGPT 自訂 GPT

ChatGPT 的伺服器在雲端，連不到你家的 localhost，所以要先開一條通道：

cloudflared tunnel --url http://127.0.0.1:8000

會拿到一個 https://xxx.trycloudflare.com 網址，把 /openapi.json 貼進自訂 GPT 的 Actions 設定即可。

⚠️ 公開服務前務必設定 FUNASR_API_TOKEN，否則任何人只要知道網址就能使用你的電腦做運算。

---

隱私

• 辨識完全在本機執行，音檔不會傳送到雲端
• 模型權重從 ModelScope 下載一次後存在本機
• HTTP API 預設只綁定 127.0.0.1，不會對外開放
• 只有在你自己主動開通道（ngrok / cloudflared）時才會對外，此時請務必設 token

---

已知限制

• 主要針對中文，其他語言請換用 FunASR 的其他模型
• 首次載入模型約需 40 秒；長時間不用可以先呼叫 preload_model 暖機
• CPU 辨識速度約為即時的 1 倍（1 分鐘音檔約需 1 分鐘），有 GPU 會快很多
• 標點斷句偶爾會切錯位置，長篇逐字稿建議人工校對
• 繁體轉換的取捨：預設的 s2twp 會一併轉換兩岸用詞，好處是「軟件→軟體、網絡→網路、 信息→資訊」都正確，但也可能過度轉換 —— 例如你說的「這份文件」會被轉成「這份檔案」 （因為 文件 在中國指的是 file）。若你的內容常出現這類詞，可改用純字形轉換： 在程式中呼叫 core.transcribe(..., opencc_config="s2t")，或用 CLI 的 --simplified 取得原始輸出後自行處理。

---

授權

本專案採用 MIT License。

底層的 FunASR 由阿里巴巴達摩院開發，其程式碼與模型權重各有授權條款，商業使用前請自行確認。