Whisper Speech Recognition MCP Server

Whisper 语音识别 MCP 服务

---

中文文档

基于 Faster Whisper 构建的高性能语音识别 MCP 服务，可高效转录音频。

功能

• 集成 Faster Whisper，实现高效语音识别
• 通过批处理加速提升转录速度
• 自动启用 CUDA 加速（如果可用）
• 支持多种模型尺寸（从 tiny 到 large-v3）
• 输出格式包括 VTT 字幕、SRT 和 JSON
• 支持批量转录文件夹中的音频文件
• 缓存模型实例，避免重复加载
• 根据 GPU 内存动态调整批次大小

安装

依赖项

• Python 3.10+
• faster-whisper>=0.9.0
• torch==2.6.0+cu126
• torchaudio==2.6.0+cu126
• mcp[cli]>=1.2.0

安装步骤

1. 克隆或下载此仓库
2. 创建并激活虚拟环境（推荐）
3. 安装依赖项：

pip install -r requirements.txt

PyTorch 安装指南

根据 CUDA 版本安装相应版本的 PyTorch：

• CUDA 12.6：

  pip install torch==2.6.0 torchvision==0.21.0 torchaudio==2.6.0 --index-url https://download.pytorch.org/whl/cu126
  

• CUDA 12.1：

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

• CPU 版本：

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

可以使用 nvcc --version 或 nvidia-smi 检查 CUDA 版本。

使用方法

启动服务

在 Windows 上，只需运行 start_server.bat。

在其他平台上，运行：

python whisper_server.py

配置 Claude Desktop

1. 打开 Claude Desktop 配置文件：

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

2. 添加 Whisper 服务配置：

{
  "mcpServers": {
    "whisper": {
      "command": "python",
      "args": ["D:/path/to/whisper_server.py"],
      "env": {}
    }
  }
}

3. 重启 Claude Desktop

可用工具

该服务提供以下工具：

1. get_model_info - 获取可用 Whisper 模型的信息
2. transcribe - 转录单个音频文件
3. batch_transcribe - 批量转录文件夹中的音频文件

性能优化建议

• 使用 CUDA 加速可显著提升转录速度
• 对大量较短的音频文件，批处理模式效率更高
• 根据 GPU 内存大小自动调整批次大小
• 使用 VAD（语音活动检测）过滤可提高长音频的准确度
• 指定正确的语言可提升转录质量

本地测试方法

1. 使用 MCP Inspector 快速测试：

mcp dev whisper_server.py

2. 使用 Claude Desktop 进行集成测试

3. 通过命令行直接调用（需要 mcp[cli]）：

mcp run whisper_server.py

错误处理

该服务实现了以下错误处理机制：

• 检查音频文件是否存在
• 处理模型加载失败
• 捕获转录过程中的异常
• GPU 内存管理
• 自适应调整批处理参数

项目结构

• whisper_server.py：主服务代码
• model_manager.py：Whisper 模型加载与缓存
• audio_processor.py：音频文件验证与预处理
• formatters.py：输出格式化（VTT、SRT、JSON）
• transcriber.py：核心转录逻辑
• start_server.bat：Windows 启动脚本

许可证

MIT

致谢

本项目在以下出色的 AI 工具和模型的协助下开发：

• GitHub Copilot - AI 编程搭档
• Trae - Agentic AI 编码助手
• Cline - AI 驱动的终端
• DeepSeek - 高级 AI 模型
• Claude-3.7-Sonnet - Anthropic 强大的 AI 助手
• Gemini-2.0-Flash - Google 的多模态 AI 模型
• VS Code - 强大的代码编辑器
• Whisper - OpenAI 的语音识别模型
• Faster Whisper - 优化版 Whisper 实现

特别感谢这些出色的工具及其背后的团队。