AI导哈

音频转录服务器

一个基于MLX Whisper的音频转录服务器，支持从磁盘、base64编码数据或YouTube视频中转录音频内容，适用于Apple Silicon Mac设备。

  • by kachiO
  • Python
  • 本地部署
  • 24 星标
  • 更新于
在 GitHub 查看 kachiO/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
  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服务器配置。 重要提示： 替换 /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 将处理为脚本定义的依赖项的安装。

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

可用工具

服务器提供以下工具：

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 看 许可证 了解详情。

相关 MCP