MLX Whisper MCP Server

MLX Whisper MCP 服务

一个简单的 Model Context Protocol（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 服务。 注意：首次运行脚本时，启动时间可能较长，因为需要下载 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 配置文件：

   # On macOS:
   code ~/Library/Application\ Support/Claude/claude_desktop_config.json
   
   # On 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 错误：如果在日志中看到 "not valid JSON" 错误，请确保服务日志输出已正确定向到 stderr

许可证

Apache License 2.0 详情请参阅 LICENSE。