Mlx Whisper MCP

MLX Whisper MCP服务器

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

特性

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

需求

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

快速开始

直接与 uv run:

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

1. 如果Claude Desktop正在运行，请重新启动它。 fastmcp 将设置启动服务器所需的配置，包括通过以下方式处理其依赖关系 uv run.

选项2：手动配置

如果您更喜欢手动配置Claude Desktop：

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

   # On macOS:
   code ~/Library/Application\ Support/Claude/claude_desktop_config.json

   # On Windows:
   code %APPDATA%\Claude\claude_desktop_config.json

1. 添加MLX Whisper MCP服务器配置。

重要提示： 替换 /absolute/path/to/mlx_whisper_mcp/ 在 cwd 下面的字段包含指向包含以下内容的目录的实际绝对路径 mlx_whisper_mcp.py 在您的系统上。

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

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

1. 重新启动克劳德桌面。

可用工具

服务器提供以下工具：

1. transcribe_file

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

参数：

• file_path：音频文件的路径
• language：（可选）强制使用特定语言的语言代码
• task：“转录”或“翻译”（翻译成英语）

2. transcribe_audio

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

参数：

• audio_data：Base64编码音频数据
• language：（可选）强制使用特定语言的语言代码
• file_format：音频文件格式（wav、mp3等）
• task：“转录”或“翻译”（翻译成英语）

3. download_youtube

下载YouTube视频。

参数：

• url：YouTube视频URL
• keep_file：如果为True，则保留下载的文件（默认值：True）

4. transcribe_youtube

下载并转录YouTube视频。

参数：

• url：YouTube视频URL
• language：（可选）强制使用特定语言的语言代码
• task：“转录”或“翻译”（翻译成英语）
• keep_file：如果为True，则保留下载的文件（默认值：True）

克劳德桌面提示示例

• “将音频文件转录到/Users/username/Destop/recording.mp3”
• “将此西班牙语录音翻译成英语”（上传音频文件时）
• “这段录音中说了什么？”（上传音频文件时）
• “下载并转录此YouTube视频：https://www.youtube.com/watch?v=dQw4w9WgXcQ"
• “下载此YouTube视频：https://www.youtube.com/watch?v=dQw4w9WgXcQ"

运作原理

此服务器使用MCP Python SDK向Claude等客户端公开MLX Whisper的转录功能。当要求转录时：

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

故障排除

• 导入错误：如果你看到MLX Whisper找不到的错误，请确保你在苹果Silicon Mac上运行
• 找不到文件：在引用音频文件时，请确保使用绝对路径
• 内存问题：对于大型型号，过长的音频文件可能会导致内存压力
• YouTube下载错误：某些视频可能受到限制或需要身份验证
• JSON错误：如果在日志中看到“无效JSON”错误，请确保服务器日志输出正确指向stderr

许可证

Apache许可证2.0 看 许可证 了解详情。