AI导哈

文本转语音服务器

一个使用MLX和Kokoro模型在macOS上实现低延迟语音合成的文本转语音服务器。

  • by ianscrivener
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 ianscrivener/mcp-tts-mlx-audio

使用说明

mcp-tts-mlx音频

在macOS上使用MLX和Kokoro进行文本到语音转换的MCP服务器。服务器将Kokoro模型加载到RAM中，用于低延迟语音合成。

特性

  • 通过MLX使用Kokoro-82M型号的快速TTS
  • 模型保持加载在RAM中，以实现最小的延迟
  • 两个MCP工具： speak 和 list_voices
  • 50+Kokoro语音可用（通常在本地缓存28个）
  • 可选语音选择（默认为af_heart）
  • 仅使用本地缓存的语音以避免下载延迟

安装

  1. 安装依赖项：
uv sync
  1. 在开发模式下安装软件包：
uv pip install -e .
  1. 配置Claude Desktop以使用MCP服务器：

编辑您的Claude Desktop配置文件：

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • 视窗: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

将以下内容添加到 mcpServers 章节：

{
  "mcpServers": {
    "mcp-tts-kokoro": {
      "command": "[FILEPATH]/mcp-tts-mlx-audio/.venv/bin/python",
      "args": [
        "[FILEPATH]/mcp-tts-mlx-audio/mcp_server.py"
      ],
      "env": {
        "HF_HUB_CACHE": "/path/to/your/huggingface/cache"
      }
    }
  }
}

重要:

  • 替换 [FILEPATH] 使用您的实际文件路径
  • 更新路径以匹配您的安装目录
  • 使用绝对路径（而不是相对路径，如 ~ 或 ./)

可选的：如果您使用自定义HuggingFace缓存位置（通过 HF_HUB_CACHE 环境变量），将其包含在 env 部分。否则，您可以省略 env 部分完全。

完整配置文件示例:

{
  "globalShortcut": "",
  "mcpServers": {
    "mcp-tts-kokoro": {
      "command": "/Users/ianscrivener/_⭐️Code_2025_M4/mcp-tts-mlx-audio/.venv/bin/python",
      "args": [
        "/Users/ianscrivener/_⭐️Code_2025_M4/mcp-tts-mlx-audio/mcp_server.py"
      ],
      "env": {
        "HF_HUB_CACHE": "/Volumes/Crucial500Gb/HUGGINGFACE_HUB_ACTIVE"
      }
    }
  }
}

如果您已经配置了其他MCP服务器，只需添加 mcp-tts-kokoro 进入您现有的 mcpServers 对象。

  1. 完全重新启动Claude Desktop（退出并重新打开）以使更改生效。

验证安装

重新启动Claude Desktop后，您应该看到可用的MCP服务器工具：

  1. 打开克劳德桌面
  2. 查找工具图标或MCP指示灯
  3. 您应该看到两个可用的工具：
    • speak -将文本转换为语音
    • list_voices -列出可用声音

如果你没有看到工具，请检查：

  • 克劳德桌面日志 对于错误（通常在 ~/Library/Logs/Claude/ 在macOS上）
  • 配置文件语法 -确保JSON有效（没有尾随逗号，引号正确）
  • 路径正确 -使用绝对路径，验证它们是否存在
  • 虚拟环境 存在于指定路径
  • Python可执行文件 -手动运行命令路径进行测试：
    /path/to/.venv/bin/python /path/to/mcp_server.py

常见问题：

  • “没有名为'mcp'的模块” -快跑 uv sync 在项目目录中
  • “找不到模型” -确保Kokoro模型已下载（手动运行服务器一次）
  • 服务器启动时崩溃 -检查所有依赖项是否已安装 uv sync

用法

MCP服务器

当Claude Desktop启动时，MCP服务器会自动运行。它将在首次启动时将Kokoro模型加载到内存中（这可能需要几秒钟）。

要在Claude Desktop之外手动测试服务器：

source .venv/bin/activate && python mcp_server.py

备注：手动运行时，您需要发送MCP协议消息。这主要用于调试。

测试所有声音

使用 test_voices.py 使用自定义文本测试所有本地下载语音的脚本：

source .venv/bin/activate && python test_voices.py "Mary had a little lamb"

这将迭代所有本地缓存的语音（通常为28个），说：

  • “声音模型A F心。玛丽有一只小羊羔”
  • “声音模型A F nova。玛丽有一只小羊羔”
  • 等等

注： 该脚本仅测试已下载到本地HuggingFace缓存的语音。它将跳过任何本地不可用的声音。这对于在不下载所有50多个声音的情况下找到您的首选声音非常有用。

MCP工具

说

将文本转换为语音并立即播放。

参数：

  • text （必填）：要转换为语音的文本
  • voice （可选）：Kokoro语音名称（默认为“af_heart”）

示例用法：

{
  "name": "speak",
  "arguments": {
    "text": "Hello world",
    "voice": "af_heart"
  }
}

list_voices

列出所有本地缓存的Kokoro语音模型。

参数： 无

示例用法：

{
  "name": "list_voices",
  "arguments": {}
}

返回一个格式化的本地下载语音列表（通常为28个），包括：

  • 美国女声（af_*）：新星、心形、贝拉、莎拉等。
  • 美国男声（am_*）：亚当、回声、迈克尔等。
  • 英国声音（bf_，bm_)爱丽丝、艾玛、乔治等。

注： 仅显示已下载到本地HuggingFace缓存的声音。完整的Kokoro模型包括50多个声音，但它们是按需下载的。

配置

  • 模型：mlx社区/科科罗-82M-bf16
  • 默认语音：af_heart

语言支持

服务器会自动从语音名称中检测正确的语言：

  • a 前缀=美式英语（af_，am_)
  • b 前缀=英式英语（bf_，bm_)
  • e 前缀=西班牙语（ef_，em_)
  • f 前缀=法语（ff_，fm_)
  • h 前缀=印地语（hf_百米)
  • i 前缀=意大利语（如果_，我_)
  • j 前缀=日语（jf_，jm_)
  • p 前缀=葡萄牙语（pf_，下午_)
  • z 前缀=普通话（zf_，zm_)

无需手动指定语言代码-根据语音自动选择正确的G2P管道。

备注

  • 模型在启动时加载一次，并保存在RAM中以进行低延迟推理
  • 要保留RAM，只需在不使用TTS功能时退出Claude Desktop
  • 每种语言在首次使用时都会创建一个单独的管道，为后续请求缓存

相关 MCP