mlx-whisper-mcp

🚀 MLX 耳语 MCP 服务器

MLX 耳语 MCP 服务器是一个简单的模型上下文协议（MCP）服务器，借助 MLX Whisper 在苹果 Silicon Mac 上实现音频转录功能，为音频处理提供便利。

✨ 主要特性

• 🍿 支持直接从磁盘转录音频文件。
• 📇 可转录 base64 编码数据中的音频。
• 📺 能下载并转录 YouTube 视频。
• 💪 使用高质量的 mlx-community/whisper-large-v3-turbo 模型。
• 📦 通过 uv run 自动管理依赖项的脚本。
• 🔍 拥有丰富的控制台输出，便于调试。
• 💾 在音频文件旁保存转录文本文件。

📦 安装指南

先决条件

• Python 3.12 或更高版本。
• 苹果 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 集成时使用此服务器？

工作原理

1. 用户向服务器发送请求，指定任务和相关参数。
2. 服务器根据任务类型执行相应的操作，例如转录音频或下载视频。
3. 处理完成后，服务器将结果返回给用户。

故障排除

• 问题：无法启动服务器
  • 检查是否安装了正确的 Python 版本和 uv 工具。
  • 确保脚本路径正确无误。
• 问题：转录失败
  • 检查输入文件的格式和路径是否正确。
  • 确保网络连接正常（对于 YouTube 下载）。
• 问题：配置不生效
  • 验证 JSON 文件语法正确，没有语法错误。
  • 确保服务器已正确重启以应用更改。

📄 许可证

此项目遵守 [LICENSE] 协议。请参考项目文档了解详细许可信息。

通过以上内容，您可以详细了解 MLX Whisper MCP 服务器的功能、使用方法及相关配置。