Local Voice Mcp

Local Voice MCP

通过运行 Chatterbox Turbo TTS 或 Kokoro TTS 本地语音模型，让 MCP 客户端能够发声。

快速入门

此软件包内置高质量女性参考语音，默认用于 Chatterbox Turbo TTS。所有环境变量均为可选项。

{
  "mcpServers": {
    "local-voice-mcp": {
      "command": "npx",
      "args": ["-y", "@codecraftersllc/local-voice-mcp"],
      "env": {
        "USE_MALE_VOICE": "false",
        "CHATTERBOX_MAX_CHARACTERS": "2000",
        "CHATTERBOX_PLAYBACK_VOLUME": "75"
      }
    }
  }
}

TTS 引擎选择

Local Voice MCP 支持两种 TTS 引擎：

Chatterbox Turbo TTS（默认）

高质量语音合成，支持语音克隆和副语言标签。可自动检测并使用适合硬件的后端。

• ✅ 跨平台支持（macOS、Windows、Linux）
• ✅ 支持使用参考音频克隆语音
• ✅ 支持用于表达情感的副语言标签（[laugh]、[sigh]、[cough] 等）
• ✅ 多架构自动检测：
  • Apple Silicon（MPS）：使用 MLX 和 mlx-community/chatterbox-turbo-6bit
  • NVIDIA GPU（CUDA）：使用 PyTorch 和 ChatterboxTurboTTS
  • CPU：使用 PyTorch 回退方案
• ✅ 模型更小（350M 参数），延迟更低

Kokoro TTS（跨平台）

使用 ONNX Runtime 的高质量开源 TTS，支持多种语言和语音。

• ✅ 跨平台（macOS、Windows、Linux）
• ✅ 支持多种语言（en-us、en-gb、fr-fr、it、ja、cmn）
• ✅ 提供 40 多种语音，可选性别和口音
• ✅ 支持语音混合
• ✅ 可调节语速
• ✅ 支持 GPU
• ✅ 支持长篇内容（无长度限制）
• ✅ 自动安装依赖项和模型（无需手动安装！）

若要使用 Kokoro，请设置 TTS_ENGINE 环境变量：

{
  "mcpServers": {
    "local-voice-mcp": {
      "command": "npx",
      "args": ["-y", "@codecraftersllc/local-voice-mcp"],
      "env": {
        "TTS_ENGINE": "kokoro",
        "KOKORO_LANGUAGE": "en-us",
        "KOKORO_VOICE": "af_sarah",
        "KOKORO_SPEED": "1.0"
      }
    }
  }
}

设置：

首次使用时，Kokoro TTS 会自动安装 Python 依赖项并下载模型文件（约 100MB）。只需配置 MCP 服务即可开始使用！

首次使用时会发生什么：

• 自动通过 pip 安装 Python 软件包（kokoro-onnx、soundfile、numpy）
• 自动下载模型文件（kokoro-v1.0.onnx 约 90MB、voices-v1.0.bin 约 13MB）
• 文件会缓存在 ~/.cache/kokoro-tts/ 中，供后续使用
• 一次性设置约需 1–2 分钟，具体取决于网络连接

手动安装（可选）：

如果你希望手动安装依赖项，或自动安装失败：

# Install Python dependencies
pip install kokoro-onnx soundfile numpy

# Model files will still auto-download, or you can download manually:
cd ~/.cache/kokoro-tts
wget https://github.com/nazdridoy/kokoro-tts/releases/download/v1.0.0/kokoro-v1.0.onnx
wget https://github.com/nazdridoy/kokoro-tts/releases/download/v1.0.0/voices-v1.0.bin

可用语音：

• 🇺🇸 美式英语：af_alloy、af_bella、af_sarah、af_nova、am_adam、am_michael、am_eric 等
• 🇬🇧 英式英语：bf_emma、bf_isabella、bm_george、bm_lewis 等
• 🇫🇷 法语：ff_siwis
• 🇮🇹 意大利语：if_sara、im_nicola
• 🇯🇵 日语：jf_alpha、jm_kumo 等
• 🇨🇳 中文：zf_xiaobei、zm_yunjian 等

语音混合： Kokoro 支持混合多种语音，打造独特的语音特征：

# 60-40 mix of two voices
KOKORO_VOICE="af_sarah:60,am_adam:40"

# Equal blend (50-50)
KOKORO_VOICE="am_adam,af_sarah"

功能

• MCP 服务实现：使用 @modelcontextprotocol/sdk 实现完整的 Model Context Protocol 服务
• HTTP API：兼容 ElevenLabs 的 REST API，可直接集成
• 文本转语音合成：使用 Chatterbox Turbo TTS 实现高质量语音合成
• 语音克隆：支持使用参考音频进行语音克隆
• 副语言标签：可直接在文本中添加 [laugh]、[sigh]、[cough] 等表达性元素
• 多架构支持：自动检测并使用最适合的后端（Apple Silicon 使用 MLX，NVIDIA 使用 CUDA，CPU 使用回退方案）
• 音量控制：可配置音频播放音量，支持跨平台
• 可靠的文件管理：自动清理临时音频文件
• 安全性：验证并清理路径，防止目录遍历
• 双模式运行：可作为 MCP 服务或 HTTP 服务运行

安装

从 npm 安装（推荐）

npm install -g local-voice-mcp

从源代码安装

git clone <repository-url>
cd local-voice-mcp
npm install
npm run build

使用方法

MCP 服务模式（默认）

通过 stdio 传输方式作为 MCP 服务运行：

local-voice-mcp-server

或使用 npx：

npx local-voice-mcp-server

HTTP 服务模式

作为 HTTP 服务运行：

MCP_MODE=http local-voice-mcp-server

或设置端口：

PORT=3000 MCP_MODE=http local-voice-mcp-server

开发

# Run MCP server in development
npm run dev:mcp

# Run HTTP server in development
npm run dev:http

# Run tests
npm test

# Build project
npm run build

MCP 工具

在 MCP 模式下运行时，可使用以下工具：

synthesize_text

使用已配置的 TTS 引擎将文本转换为语音并返回音频数据。

常用参数：

• text（字符串，必填）：要合成的文本

Chatterbox Turbo 专属参数：

• referenceAudio（字符串，可选）：用于声音克隆的参考音频路径

**注意：**Chatterbox Turbo 会直接在文本中使用副语言标签，而不是韵律参数。若要生成富有表现力的语音，请在文本中加入 [laugh]、[sigh]、[cough]、[chuckle]、[gasp]、[groan]、[clear throat]、[sniff]、[shush] 等标签。

Kokoro 专属参数：

• speed（数字，可选）：语速（0.5-2.0，默认值：1.0）
• language（字符串，可选）：语言代码（例如，'en-us'、'en-gb'、'fr-fr'、'ja'、'cmn'，默认值：'en-us'）
• voice（字符串，可选）：语音名称（例如，'af_sarah'、'am_adam'、'bf_emma'，默认值：'af_sarah'）
• model_path（字符串，可选）：Kokoro ONNX 模型文件的路径
• voices_path（字符串，可选）：Kokoro voices bin 文件的路径

返回：

• 包含合成状态和文件路径的 JSON 响应

响应示例：

{
  "success": true,
  "message": "Speech synthesis completed successfully",
  "audioFile": "/tmp/local-voice-mcp/audio_20240115_103000_abc123.wav",
  "textLength": 25,
  "audioFormat": "wav",
  "engine": "chatterbox",
  "engineName": "chatterbox",
  "options": {},
  "generatedAt": "2024-01-15T10:30:00.000Z"
}

音频文件会保存到临时目录，可使用任意音频播放器播放，也可以通过程序访问。

play_audio

使用系统默认音频播放器播放音频文件，并可选择控制音量。

参数：

• audioFile（字符串，必填）：要播放的音频文件路径
• volume（数字，可选）：播放音量百分比（0-100）。如果未指定，则使用 CHATTERBOX_PLAYBACK_VOLUME 环境变量，或默认值 50。

支持的格式：

• WAV 文件（.wav）
• MP3 文件（.mp3）

返回：

• 包含播放状态和系统信息的 JSON 响应

响应示例：

{
  "success": true,
  "message": "Successfully played audio file: /tmp/local-voice-mcp/audio_123.wav",
  "audioFile": "/tmp/local-voice-mcp/audio_123.wav",
  "volume": 50,
  "platform": "darwin",
  "command": "afplay -v 0.5 /tmp/local-voice-mcp/audio_123.wav",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

平台支持：

• 跨平台：优先使用 ffplay（来自 ffmpeg），以便在所有平台上实现一致的音量控制
• macOS：使用 afplay 命令和 -v 音量标志作为后备方案
• Windows：使用 PowerShell、MediaPlayer 和音量控制作为后备方案
• Linux：使用带增益控制的 mpg123（MP3）或 aplay（WAV，不支持音量控制）作为后备方案

tts_status

返回 TTS 服务的当前状态。

**参数：**无

返回：

• 包含服务状态和功能的 JSON 响应

响应示例：

{
  "success": true,
  "status": "operational",
  "message": "TTS service is ready and operational",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "service": {
    "name": "Chatterbox TTS",
    "version": "0.1.0",
    "capabilities": [
      "text-to-speech synthesis",
      "voice cloning with reference audio",
      "prosody controls"
    ]
  }
}

MCP 资源

service-info

提供有关 Local Voice MCP 服务的信息。

URI：local-voice://service-info

HTTP API

在 HTTP 模式下运行时，服务会提供：

POST /tts

兼容 ElevenLabs 的文本转语音端点。

请求头：

• X-API-Key：API 密钥（身份验证占位符）
• Content-Type：application/json

请求正文：

{
  "text": "[sigh] Hello, world! [laugh] This is great!",
  "options": {
    "referenceAudio": "path/to/reference.wav"
  }
}

响应：

• Content-Type：audio/wav
• 二进制音频数据

配置

环境变量

服务配置

• PORT：HTTP 服务端口（默认值：59125）
• MCP_MODE：运行模式——"mcp" 或 "http"（默认值："mcp"）

TTS 引擎选择

• TTS_ENGINE：要使用的 TTS 引擎——"chatterbox"、"kani-mlx" 或 "kokoro"（默认值："chatterbox"）

Chatterbox Turbo TTS 配置

这些环境变量可用于设置 Chatterbox Turbo TTS 合成的默认值。如果合成方法传入的选项未覆盖这些值，则会使用它们：

• PYTHON_PATH：Python 解释器的路径（默认值："python3"）。**重要提示：**如果在 Apple Silicon 上使用 Python 3.13 或更高版本，请将其指向安装了 mlx-audio 的 Python 3.11-3.12 conda 环境。
• CHATTERBOX_REFERENCE_AUDIO：用于语音克隆的参考音频文件路径（可位于系统任意位置，支持 .wav、.mp3、.flac、.ogg、.m4a、.aac）。如果未指定，则使用随附的高品质女性参考语音。
• USE_MALE_VOICE：使用男性语音替代随附的女性参考语音（true/false，默认值：false）。设为 true 时，将使用 Chatterbox 的默认男性语音，而不是随附的女性语音。仅当未指定自定义参考音频时，此设置才会生效。
• CHATTERBOX_MAX_CHARACTERS：文本输入允许的最大字符数（整数，默认值：2000）
• CHATTERBOX_OUTPUT_DIR：生成的音频文件的输出目录（默认值：系统临时目录 + "local-voice-mcp"）
• CHATTERBOX_PLAYBACK_VOLUME：默认音频播放音量百分比（整数，0-100，默认值：50）

**副语言标签：**可直接在文本中使用副语言标签，而不是韵律控制：[laugh]、[sigh]、[cough]、[chuckle]、[gasp]、[groan]、[clear throat]、[sniff]、[shush]

示例："[sigh] I can't believe it's Monday again. [laugh] But let's make the best of it!"

Kokoro 配置

这些环境变量可用于设置 Kokoro 合成的默认值：

• KOKORO_SPEED：语速（浮点数，0.5-2.0，默认值：1.0）
• KOKORO_LANGUAGE：语言代码（字符串，默认值："en-us"）。支持：en-us、en-gb、fr-fr、it、ja、cmn
• KOKORO_VOICE：语音名称（字符串，默认值："af_sarah"）。请参阅上方的可用语音。也可使用语音混合格式，例如 "voice1:weight,voice2:weight"
• KOKORO_MODEL_PATH：kokoro ONNX 模型文件的路径（字符串，默认值："kokoro-v1.0.onnx"）
• KOKORO_VOICES_PATH：voices bin 文件的路径（字符串，默认值："voices-v1.0.bin"）
• KOKORO_MAX_CHARACTERS：文本输入允许的最大字符数（整数，默认值：5000）
• KOKORO_OUTPUT_DIR：生成的音频文件的输出目录（默认值：系统临时目录 + "local-voice-mcp"）
• PYTHON_PATH：Python 解释器的路径（默认值："python3"）

示例：

# Set default TTS parameters via environment variables
# Reference audio can be anywhere on your system
export CHATTERBOX_REFERENCE_AUDIO="/Users/john/Music/my-voice.wav"
export CHATTERBOX_MAX_CHARACTERS="3000"
export CHATTERBOX_PLAYBACK_VOLUME="75"

# Run the MCP server with these defaults
local-voice-mcp-server

使用 npx：

{
  "mcpServers": {
    "local-voice-mcp": {
      "command": "npx",
      "args": ["-y", "@codecraftersllc/local-voice-mcp"],
      "env": {
        "CHATTERBOX_REFERENCE_AUDIO": "/Users/john/Music/my-voice.wav",
        "CHATTERBOX_MAX_CHARACTERS": "3000",
        "CHATTERBOX_PLAYBACK_VOLUME": "75"
      }
    }
  }
}

使用男性语音替代随附的女性语音：

{
  "mcpServers": {
    "local-voice-mcp": {
      "command": "npx",
      "args": ["-y", "@codecraftersllc/local-voice-mcp"],
      "env": {
        "USE_MALE_VOICE": "true"
      }
    }
  }
}

优先级顺序：

1. 传递给 synthesize_text 或 play_audio 工具的选项（最高优先级）
2. 环境变量
3. 内置默认值（最低优先级）

MCP 客户端配置

添加到 MCP 客户端配置中：

{
  "local-voice-mcp": {
    "command": "npx",
    "args": ["-y", "local-voice-mcp-server"],
    "env": {}
  }
}

使用 Cursor 进行测试

Cursor 是一款广受欢迎、由 AI 驱动且支持 MCP 的代码编辑器。以下介绍如何使用 Cursor 测试 Local Voice MCP 服务：

1. 安装软件包

首先，全局安装软件包或确保其可用：

npm install -g local-voice-mcp
# or
npm install local-voice-mcp

2. 配置 Cursor

将 MCP 服务添加到 Cursor 配置文件中。文件位置取决于操作系统：

• macOS：~/Library/Application Support/Cursor/User/globalStorage/cursor.mcp/config.json
• Windows：%APPDATA%\Cursor\User\globalStorage\cursor.mcp\config.json
• Linux：~/.config/Cursor/User/globalStorage/cursor.mcp/config.json

添加以下配置：

{
  "mcpServers": {
    "local-voice-mcp": {
      "command": "local-voice-mcp-server",
      "args": [],
      "env": {}
    }
  }
}

或者，如果使用 npx：

{
  "mcpServers": {
    "local-voice-mcp": {
      "command": "npx",
      "args": ["-y", "local-voice-mcp-server"],
      "env": {}
    }
  }
}

3. 重启 Cursor

添加配置后，重启 Cursor 以加载 MCP 服务。

4. 测试集成

重启 Cursor 后，即可测试 TTS 功能：

1. 打开 Cursor 的 AI 聊天

2. 让 Cursor 使用 TTS 工具：

   Can you synthesize speech for "Hello, this is a test of the local voice MCP server"?
   

3. 检查 TTS 状态：

   What's the status of the TTS service?
   

4. 使用副语言标签进行测试：

   Synthesize "[sigh] Welcome to the future of AI coding. [laugh] It's going to be amazing!"
   

5. 测试音频播放：

   Play the audio file that was just generated
   

6. 测试音量控制：

   Play the audio file at 25% volume
   

5. 验证工具是否可用

你应该能在 Cursor 中看到以下工具：

• synthesize_text - 用于文本转语音
• play_audio - 用于通过系统音频播放音频文件
• tts_status - 用于检查服务状态

6. 故障排除

如果 MCP 服务未显示在 Cursor 中：

1. 检查日志：在 Cursor 的开发者控制台中查找错误消息
2. 验证安装：在终端中直接运行 local-voice-mcp-server，确保其正常工作
3. 检查路径：确保配置中的命令路径正确
4. 重启 Cursor：更改配置后，有时需要完全重启
5. JSON 解析错误：如果看到“Unexpected token”错误，请确保使用的是支持正确标准输入/输出日志记录的最新版本

7. 预期行为

正常工作时：

• Cursor 将能够调用 TTS 工具
• 你将收到包含文件路径的结构化 JSON 响应
• 音频文件将保存到临时目录
• TTS 服务将使用 Chatterbox Turbo TTS 引擎
• 可以使用系统音频播放器播放文件

所有响应均采用结构化 JSON 格式，并包含清晰的文件路径，便于 MCP 客户端和 AI Agent 理解并处理结果。

要求

• Node.js 16+
• Python 3.10-3.12（mlx-audio 依赖项尚不支持 Python 3.13+）
• PyTorch（用于 CUDA/CPU 后端）
• 对于 Apple Silicon：pip install mlx-audio
• 对于 CUDA/CPU：pip install chatterbox-tts

**Apple Silicon 用户须知：**由于依赖项限制，mlx-audio 软件包要求 Python <3.13。如果你的系统 Python 版本为 3.13+，则需要使用 conda 环境：

# Create a Python 3.11 environment for Chatterbox
conda create -n chatterbox python=3.11
conda activate chatterbox
pip install mlx-audio

# Then set PYTHON_PATH in your MCP config to point to this environment

{
  "mcpServers": {
    "local-voice-mcp": {
      "command": "npx",
      "args": ["-y", "@codecraftersllc/local-voice-mcp"],
      "env": {
        "TTS_ENGINE": "chatterbox",
        "PYTHON_PATH": "/path/to/miniconda3/envs/chatterbox/bin/python"
      }
    }
  }
}

服务会自动检测你的硬件并使用最佳后端：

平台	后端	模型
Apple Silicon（通过 MLX）	MLX	mlx-community/chatterbox-turbo-6bit
NVIDIA GPU（CUDA）	PyTorch	ChatterboxTurboTTS
CPU	PyTorch	ChatterboxTurboTTS（速度较慢）

架构

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   MCP Client    │    │  HTTP Client     │    │   CLI Tool      │
│ (Cursor, etc.)  │    │                  │    │                 │
└─────────┬───────┘    └─────────┬────────┘    └─────────┬───────┘
          │                      │                       │
          │ stdio                │ HTTP                  │ stdio
          │                      │                       │
          ▼                      ▼                       ▼
    ┌─────────────────────────────────────────────────────────────┐
    │              Local Voice MCP Server                         │
    │  ┌─────────────────┐    ┌─────────────────────────────────┐ │
    │  │   MCP Server    │    │         HTTP Server             │ │
    │  │   (stdio)       │    │      (Express.js)               │ │
    │  └─────────────────┘    └─────────────────────────────────┘ │
    │                                   │                         │
    │  ┌─────────────────────────────────────────────────────────┐ │
    │  │              TTS Tools & Services                       │ │
    │  │  ┌─────────────────┐    ┌─────────────────────────────┐ │ │
    │  │  │ ChatterboxService│    │    File Management         │ │ │
    │  │  │                 │    │   (Cleanup & Security)     │ │ │
    │  │  └─────────────────┘    └─────────────────────────────┘ │ │
    │  └─────────────────────────────────────────────────────────┘ │
    └─────────────────────────────────────────────────────────────┘
                                   │
                                   ▼
                        ┌─────────────────────┐
                        │   Python TTS        │
                        │ (Chatterbox Turbo)  │
                        └─────────────────────┘

许可证

MIT

贡献

1. Fork 此仓库
2. 创建功能分支
3. 进行更改
4. 为新功能添加测试
5. 确保所有测试均通过
6. 提交拉取请求