Local Speech-to-Text MCP Server

本地语音转文字 MCP 服务

一款高性能 Model Context Protocol（MCP）服务，使用 whisper.cpp 在本地进行语音转录，并针对 Apple Silicon 进行了优化。

🎯 功能

• 🏠 100% 本地处理：不使用云端 API，全面保护隐私
• 🚀 针对 Apple Silicon 优化：转录速度超过实时速度的 15 倍
• 🎤 说话人分离：识别并区分多位说话人
• 🎵 通用音频格式支持：自动转换 MP3、M4A、FLAC 等格式
• 📝 多种输出格式：txt、json、vtt、srt、csv
• 💾 内存占用低：内存使用量低于 2GB
• 🔧 TypeScript：全面的类型安全与现代化开发体验

🚀 快速开始

先决条件

• Node.js 18+
• whisper.cpp（brew install whisper-cpp）
• 音频格式转换所需：ffmpeg（brew install ffmpeg）——可自动处理 MP3、M4A、FLAC、OGG 等格式
• 说话人分离所需：Python 3.8+ 和 HuggingFace 令牌（免费）

支持的音频格式

• whisper.cpp 原生支持的格式：WAV、FLAC
• 自动转换的格式：MP3、M4A、AAC、OGG、WMA 等
• 自动转换：由 ffmpeg 提供支持，并针对 whisper.cpp 优化为 16kHz/单声道
• 格式检测：按需自动检测并转换格式

安装

git clone https://github.com/your-username/local-stt-mcp.git
cd local-stt-mcp/mcp-server
npm install
npm run build

# Download whisper models
npm run setup:models

# For speaker diarization, set HuggingFace token
export HF_TOKEN="your_token_here"  # Get free token from huggingface.co

说话人分离说明：需要 HuggingFace 账户，并接受 pyannote/speaker-diarization-3.1 许可协议。

MCP 客户端配置

将以下内容添加到 MCP 客户端配置中：

{
  "mcpServers": {
    "whisper-mcp": {
      "command": "node",
      "args": ["path/to/local-stt-mcp/mcp-server/dist/index.js"]
    }
  }
}

🛠️ 可用工具

工具	描述
transcribe	基础音频转录，支持自动格式转换
transcribe_long	通过分块处理长音频文件，并支持格式转换
transcribe_with_speakers	支持格式处理的说话人分离与转录
list_models	显示可用的 whisper 模型
health_check	系统诊断
version	服务版本信息

📊 性能

Apple Silicon 基准测试：

• 处理速度：实时速度的 15.8 倍（WhisperX 为 5.5 倍）
• 内存使用量：低于 2GB（WhisperX 约为 4GB）
• GPU 加速：✅ Apple Neural Engine
• 设置：复杂度中等，但性能更出色

详细性能对比请参阅 /benchmarks/。

🏗️ 项目结构

mcp-server/
├── src/                    # TypeScript source code
│   ├── tools/             # MCP tool implementations
│   ├── whisper/           # whisper.cpp integration
│   ├── utils/             # Speaker diarization & utilities
│   └── types/             # Type definitions
├── dist/                  # Compiled JavaScript
└── python/                # Python dependencies

🔧 开发

# Build
npm run build

# Development mode (watch)
npm run dev

# Linting & formatting
npm run lint
npm run format

# Type checking
npm run type-check

🤝 贡献

1. Fork 仓库
2. 创建功能分支
3. 进行更改
4. 添加测试
5. 提交 pull request

📄 许可证

MIT 许可证——详情请参阅 LICENSE 文件。

🙏 致谢

• whisper.cpp：提供优化后的推理
• OpenAI Whisper：提供原始模型
• Model Context Protocol：提供框架
• Pyannote.audio：提供说话人分离功能