MLX Whisper MCP 服务器

一个简单的模型上下文协议 (MCP) 服务器，它使用 Apple Silicon Mac 上的 MLX Whisper 提供音频转录功能。

特性

• 直接从磁盘转录音频文件
• 从 base64 编码的数据转录音频
• 下载并转录 YouTube 视频
• 使用高质量的 mlx-community/whisper-large-v3-turbo 模型
• 自包含脚本，通过 uv run 自动管理依赖项
• 丰富的控制台输出，便于调试
• 将转录文本文件与音频文件一起保存

要求

• Python 3.12 或更高版本
• Apple Silicon Mac (M 系列)
• 已安装 uv (pip install uv 或 curl -sS https://astral.sh/uv/install.sh | bash)

快速开始

直接使用 uv run 运行：

uv run mlx_whisper_mcp.py

就是这样！该脚本将自动安装其自身的依赖项并启动 MCP 服务器。

与 Claude Desktop 一起使用

1. 编辑您的 Claude Desktop 配置文件：

# 在 macOS 上：
code ~/Library/Application\ Support/Claude/claude_desktop_config.json

# 在 Windows 上：
code %APPDATA%\Claude\claude_desktop_config.json

2. 添加 MLX Whisper MCP 服务器配置：

{
  "mcpServers": {
    "mlx-whisper": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/mlx_whisper_mcp/",
        "run",
        "mlx_whisper_mcp.py"
      ]
    }
  }
}

3. 重启 Claude Desktop

可用工具

服务器提供以下工具：

1. transcribe_file

从磁盘上的路径转录音频文件。

参数：

• file_path: 音频文件的路径
• language: (可选) 强制指定特定语言的语言代码
• task: "transcribe" 或 "translate" (翻译成英语)

2. transcribe_audio

从 base64 编码的数据转录音频。

参数：

• audio_data: Base64 编码的音频数据
• language: (可选) 强制指定特定语言的语言代码
• file_format: 音频文件格式 (wav, mp3 等)
• task: "transcribe" 或 "translate" (翻译成英语)

3. download_youtube

下载 YouTube 视频。

参数：

• url: YouTube 视频 URL
• keep_file: 如果为 True，则保留下载的文件 (默认值: True)

4. transcribe_youtube

下载并转录 YouTube 视频。

参数：

• url: YouTube 视频 URL
• language: (可选) 强制指定特定语言的语言代码
• task: "transcribe" 或 "translate" (翻译成英语)
• keep_file: 如果为 True，则保留下载的文件 (默认值: True)

Claude Desktop 的示例提示

• "转录位于 /Users/username/Desktop/recording.mp3 的音频文件"
• "将此西班牙语录音翻译成英语" (上传音频文件时)
• "这段录音里说了什么？" (上传音频文件时)
• "下载并转录此 YouTube 视频：https://www.youtube.com/watch?v=dQw4w9WgXcQ"
• "下载此 YouTube 视频：https://www.youtube.com/watch?v=dQw4w9WgXcQ"

工作原理

此服务器使用 MCP Python SDK 将 MLX Whisper 的转录功能公开给像 Claude 这样的客户端。当请求转录时：

1. 接收音频数据（作为文件路径、base64 编码的数据或 YouTube URL）
2. 对于 YouTube URL，视频将下载到 ~/.mlx-whisper-mcp/downloads
3. 对于 base64 数据，将创建一个临时文件
4. MLX Whisper 用于执行转录
5. 转录文本保存到音频文件旁边的 .txt 文件中
6. 转录文本返回给客户端
7. 清理临时文件（除非 keep_file=True）

故障排除

• 导入错误: 如果您看到有关找不到 MLX Whisper 的错误，请确保您在 Apple Silicon Mac 上运行
• 找不到文件: 确保您在使用绝对路径引用音频文件
• 内存问题: 非常长的音频文件可能会导致大型模型的内存压力
• YouTube 下载错误: 某些视频可能受到限制或需要身份验证
• JSON 错误: 如果您在日志中看到“not valid JSON”错误，请确保服务器日志输出已正确定向到 stderr

许可证

Apache License 2.0 有关详细信息，请参见 LICENSE。