mcp-tts-mlx音频
在macOS上使用MLX和Kokoro进行文本到语音转换的MCP服务器。服务器将Kokoro模型加载到RAM中，用于低延迟语音合成。
特性
- 通过MLX使用Kokoro-82M型号的快速TTS
- 模型保持加载在RAM中，以实现最小的延迟
- 两个MCP工具：
speak和list_voices - 50+Kokoro语音可用（通常在本地缓存28个）
- 可选语音选择（默认为af_heart）
- 仅使用本地缓存的语音以避免下载延迟
安装
- 安装依赖项：
uv sync- 在开发模式下安装软件包：
uv pip install -e .- 配置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 对象。
- 完全重新启动Claude Desktop（退出并重新打开）以使更改生效。
验证安装
重新启动Claude Desktop后，您应该看到可用的MCP服务器工具：
- 打开克劳德桌面
- 查找工具图标或MCP指示灯
- 您应该看到两个可用的工具：
- 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
- 每种语言在首次使用时都会创建一个单独的管道，为后续请求缓存