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 服务器的功能、使用方法及相关配置。