Skip to main content
Glama
funasr-zh-tw-mcp

funasr-zh-tw-mcp

by draiagent

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 可以串接


Related MCP server: io.github.chicogong/ffvoice

支援哪些 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 由阿里巴巴達摩院開發,其程式碼與模型權重各有授權條款,商業使用前請自行確認。

Available Tools

2 tools
preload_model預先載入模型A

預先把 FunASR 模型載入記憶體,讓之後的 transcribe_audio 呼叫可以立即開始辨識。首次執行會下載約 1.5GB 的模型權重。模型已載入時呼叫不會有任何副作用。

Inputs: no named parameters. Returns: 模型預載結果。

transcribe_audio音檔轉繁體逐字稿A

將本機音檔轉成繁體中文逐字稿,支援 wav/mp3/m4a/flac/ogg/mp4 等格式。全程在本機運算,音檔不會上傳到任何雲端服務。注意:模型第一次載入約需 40 秒,若使用者在意等待時間可先呼叫 preload_model。

Inputs: file_path (required), traditional, with_timestamps. Returns: 辨識結果。回傳型別要明確標註,MCP 才能產生 output schema 給用戶端。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 2 tools

    Disambiguation5/5

    transcribe_audio performs the core transcription while preload_model handles model initialization; their purposes are completely distinct and cannot be confused. The descriptions clearly separate the main task from an optional optimization step.

    Naming Consistency5/5

    Both tools follow the same verb_noun pattern: transcribe_audio and preload_model. The verb clearly indicates the action, and the noun indicates the target, making the naming predictable and consistent.

    Tool Count5/5

    Two tools is appropriate for a narrow-purpose server: one primary transcription tool plus an optional model preloading optimization. Each tool earns its place without redundancy, and adding more tools would likely be unnecessary for this focused scope.

    Completeness5/5

    The server's domain is local audio transcription, and the tool set covers the full workflow: optional model preloading followed by transcription. There are no obvious gaps for the stated purpose, and the preload_model tool explicitly handles the cold-start concern.

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      A powerful speech-to-text MCP server that supports multiple audio formats and recognition engines including remote APIs (Bailian, OpenAI Whisper, iFLYTEK), Google Speech Recognition, and CMU Sphinx.
      1
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      A high-performance speech recognition MCP server based on Faster Whisper, providing efficient audio transcription capabilities with support for multiple model sizes, batch processing, and various output formats.
      19
      -