MCP Whisper Transcription

MCP Whisper转录服务器

使用MLX优化的Whisper模型进行音频/视频转录的MCP（模型上下文协议）服务器。针对具有超快性能的Apple Silicon设备进行了优化。

✨ 特性

• 🚀 MLX优化：利用Apple Silicon实现超快转录（速度高达10倍）
• 🎯 多种格式：支持txt、md、srt和json输出格式
• 🎬 视频支持：自动从视频文件（MP4、MOV、AVI、MKV）中提取音频
• 📦 批处理：使用可配置的workers并行处理多个文件
• 🔧 MCP集成：通过工具和资源提供全面的MCP协议支持
• 📊 性能跟踪：内置性能监控和报告
• 🎛️ 柔性模型：从6种不同的Whisper型号中选择（从小型到大型v-3-turbo）
• 🛠️ 错误处理：强大的错误处理和验证
• 📈 并发处理：线程安全并发转录支持
• 🔇 语音活动检测：可选VAD，可消除静音并加快处理速度
• 🧹 幻觉预防：高级过滤以删除常见的转录伪影

🏆 演出

• 速度：在Apple Silicon上高达10倍的实时转录
• 记忆：优化了内存使用（大多数文件\<500MB）
• 并发：同时处理多个转录
• 可扩展的：高效地批量处理数百个文件

🚀 快速开始

先决条件

• 苹果硅Mac （M1、M2、M3或更高版本）
• Python 3.10+
• 转码 （用于视频支持）

安装

1. 安装FFmpeg （如果尚未安装）：

   brew install ffmpeg

1. 克隆存储库:

   git clone https://github.com/galacoder/mcp-whisper-transcription.git
   cd mcp-whisper-transcription

1. 安装诗歌 （如果尚未安装）：

   curl -sSL https://install.python-poetry.org | python3 -

1. 安装依赖项:

   poetry install

1. 测试安装:

   poetry run python src/whisper_mcp_server.py --help

📋 配置

环境变量

创建一个 .env 要自定义设置的文件：

# Model Configuration
DEFAULT_MODEL=mlx-community/whisper-large-v3-turbo
OUTPUT_FORMATS=txt,md,srt,json

# Performance Settings
MAX_WORKERS=4
TEMP_DIR=./temp

# Optional: API Keys for future cloud features
# OPENAI_API_KEY=your_key_here

可用型号

🔧 用法

Claude桌面集成

添加到您的Claude Desktop配置文件中：

{
  "mcpServers": {
    "whisper-transcription": {
      "command": "poetry",
      "args": ["run", "python", "src/whisper_mcp_server.py"],
      "cwd": "/absolute/path/to/mcp-whisper-transcription"
    }
  }
}

📍 配置文件位置：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• 视窗: %APPDATA%\Claude\claude_desktop_config.json

独立使用

# Run the MCP server directly
poetry run python src/whisper_mcp_server.py

# Or use the development server
poetry run python -m src.whisper_mcp_server

🛠️ 可用工具和资源

MCP工具

MCP资源

快速示例

# Single file transcription
result = await client.call_tool("transcribe_file", {
    "file_path": "interview.mp4",
    "output_formats": "txt,srt",
    "model": "mlx-community/whisper-large-v3-turbo"
})

# Transcription with Voice Activity Detection
result = await client.call_tool("transcribe_file", {
    "file_path": "long_interview.mp4",
    "output_formats": "txt,srt",
    "use_vad": True  # Remove silence for faster processing
})

# Batch processing
result = await client.call_tool("batch_transcribe", {
    "directory": "./podcasts",
    "pattern": "*.mp3",
    "max_workers": 4
})

# Check supported formats
formats = await client.call_tool("get_supported_formats", {})

🧪 发展

运行测试

# Run all tests
poetry run pytest

# Run with coverage
poetry run pytest --cov=src --cov-report=html

# Run specific test file
poetry run pytest tests/test_mcp_tools.py -v

代码质量

# Format code
poetry run black .
poetry run isort .

# Type checking (optional)
poetry run mypy src/

# Lint code
poetry run flake8 src/

项目结构

mcp-whisper-transcription/
├── src/
│   └── whisper_mcp_server.py    # Main MCP server
├── tests/                       # Comprehensive test suite
├── examples/                    # Usage examples and test files
├── transcribe_mlx.py           # MLX Whisper integration
├── whisper_utils.py            # Utility functions
└── pyproject.toml              # Project configuration

📊 性能基准

测试结果（苹果M3 Max）

🔧 故障排除

常见问题

1. 未找到FFmpeg

   brew install ffmpeg

1. 模型下载缓慢

- 模型缓存在 ~/.cache/huggingface/ - 第一次下载可能很慢，但后续运行很快

1. 内存问题

- 对大文件使用较小的模型（小/基本） - 减少 MAX_WORKERS 用于并发处理

1. 权限错误

- 确保文件权限正确 - 检查输出目录的写入权限

看 故障排除.md 详细的解决方案。

📋 需求

• Python 3.10+
• 苹果硅Mac （M1、M2、M3或更高版本）
• 转码 （用于视频文件支持）
• 4GB+内存 （建议大型型号使用8GB+）
• 2GB以上可用磁盘空间 （用于模型缓存）

📄 许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

🤝 贡献

欢迎投稿！请看 贡献.md 作为指导方针。

🙏 致谢

• 内置于 FastMCP -现代MCP服务器框架
• 由...驱动 MLX耳语 -苹果硅优化
• 原创 耳语 OpenAI-革命性的语音识别
• 感谢苹果MLX团队令人难以置信的性能优化