# 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（大部分人）：**
```bash
pip install torch torchaudio --index-url https://download.pytorch.org/whl/cpu
```

**有 NVIDIA 顯卡（速度快很多）：**
```bash
pip install torch torchaudio --index-url https://download.pytorch.org/whl/cu121
```

### 2. 裝本專案

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

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

```bash
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 分鐘**，請耐心等候。

---

## 用法一：命令列

```bash
funasr-transcribe 課堂錄音.m4a
```

輸出到檔案：

```bash
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

```bash
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`

```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

```bash
funasr-api
```

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

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

範例：

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

從自己的網頁工具呼叫：

```javascript
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，所以要先開一條通道：

```bash
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](https://github.com/modelscope/FunASR) 由阿里巴巴達摩院開發，其程式碼與模型權重各有授權條款，商業使用前請自行確認。