asr-mcp

基于本地 Whisper Large V3 (MLX) 模型的语音转文本 MCP 服务（stdio 传输）。转写全程本地运行，不联网、不上传音频。

功能

对外暴露两个 MCP 工具：

工具	说明
transcribe_audio	将音频转写为文本，支持三种输出：text 纯文本含标点（默认）/ timestamps 带时间轴 / srt 字幕
correct_transcription	调用当前会话的 LLM 对转写结果纠错，支持 semantic（语义/术语纠错，默认）和 reference（对照标准文稿纠错，适合字幕制作）两种模式

设计要点：

• 工具调用与重任务解耦：转写在独立子进程（worker.py）中执行，server 以事件驱动方式等待并每 15 秒上报心跳进度，不轮询进程状态。
• 超时语义诚实：默认超时 10 分钟；超时后不杀子进程，任务继续在后台跑完并自行落盘，工具如实返回「未完成」而非「出错」，并提示稍后检查输出文件。
• 中文标点修复：该模型转写中文时默认不输出任何标点，本服务按语言注入 initial_prompt 引导生成规范标点。
• Sampling 优雅回退：纠错优先走 MCP Sampling；客户端不支持时（多数客户端的现状），工具返回一份现成的纠错提示词，由当前会话的 LLM 直接完成纠错。

环境要求

• macOS + Apple Silicon（MLX 仅支持 Apple 芯片）
• Python ≥ 3.12
• uv 包管理器
• 本地模型目录（见下节）

安装

git clone https://github.com/fengredrum/asr-mcp.git
cd asr-mcp
uv sync

本项目默认 PyPI 索引为阿里云镜像（见 pyproject.toml），海外网络可在 [tool.uv] 中删除或替换该配置。

准备模型

下载模型到本地任意目录，例如：

huggingface-cli download mlx-community/whisper-large-v3-mlx --local-dir ~/models/whisper-large-v3-mlx

通过环境变量 ASR_MCP_MODEL_PATH 指定模型目录（也支持直接填 Hugging Face 仓库 ID，mlx_whisper 会自动下载）：

export ASR_MCP_MODEL_PATH=~/models/whisper-large-v3-mlx

接入 MCP 客户端

以 Claude Code 为例：

claude mcp add asr-mcp \
  --env ASR_MCP_MODEL_PATH=$HOME/models/whisper-large-v3-mlx \
  -- uv --directory /绝对路径/asr-mcp run server.py

或在客户端的 MCP 配置中手动添加：

{
  "mcpServers": {
    "asr-mcp": {
      "command": "uv",
      "args": ["--directory", "/绝对路径/asr-mcp", "run", "server.py"],
      "env": {
        "ASR_MCP_MODEL_PATH": "/你的模型目录/whisper-large-v3-mlx"
      }
    }
  }
}

接入后直接让 LLM「转写这个音频文件」即可，它会调用 transcribe_audio 并在完成后询问是否需要纠错。

调试转写链路

可绕过 MCP 直接运行 worker：

.venv/bin/python worker.py <音频路径> <text|timestamps|srt> <输出文件> [语言]

输出文件命名约定

类型	文件名
纯文本	{音频名}.txt
时间轴	{音频名}_timestamps.txt
字幕	{音频名}.srt
纠错结果（约定）	{音频名}_corrected.txt

输出默认与音频文件同目录，也可由调用方指定输出目录。

项目结构

server.py        # MCP server：工具定义、子进程调度、心跳进度、Sampling 回退
worker.py        # 一次性转写工作进程，stdout 最后一行 JSON 为状态协议
transcriber.py   # mlx_whisper.transcribe 薄封装（含中文标点 workaround）
formatter.py     # text / timestamps / srt 三种格式化输出

许可证

MIT