MLX Whisper MCP 服务器

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

特性

• 直接从磁盘转录音频文件
• 转录 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 mlx_whisper_mcp.py

就这样！该脚本会自动安装其依赖项并启动 MCP 服务器。 注意：第一次运行脚本时，可能需要更长时间启动，因为它会下载 Whisper 模型（约 1.6GB）。后续运行会更快。

与 Claude Desktop 集成

有两种主要方式将此服务器与 Claude Desktop 集成：

方案 1：使用 uv（推荐）

1. 导航到您克隆或保存 mlx_whisper_mcp.py 的目录。
2. 运行以下命令：

   uv tool run fastmcp install mlx_whisper_mcp.py
   

3. 如果 Claude Desktop 正在运行，请重启它。fastmcp 将设置必要的配置以启动服务器，包括通过 uv run 处理其依赖项。

方案 2：手动配置

如果您希望手动配置 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 服务器配置。 重要： 将下面 cwd 字段中的 /absolute/path/to/mlx_whisper_mcp/ 替换为您系统中包含 mlx_whisper_mcp.py 的实际绝对路径。

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

   此配置告诉 Claude Desktop 使用 uv run 执行 mlx_whisper_mcp.py，并将当前工作目录 (cwd) 设置为脚本的位置。uv run 将处理为脚本定义的依赖项安装。

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 错误：如果在日志中看到“不是有效的 JSON”错误，请确保服务器的日志输出正确指向 stderr

许可证

Apache 许可证 2.0 详情见 LICENSE。