项目简介

本地语音MCP服务器（Local Voice MCP）是一个基于Model Context Protocol (MCP) 构建的后端服务，旨在为LLM（大型语言模型）客户端提供强大的本地文本转语音（Text-to-Speech, TTS）和音频播放功能。它允许LLM客户端通过标准化的方式调用工具，实现语音合成和播放，从而增强LLM应用的交互性。

主要功能点

MCP服务器实现：遵循Model Context Protocol标准，与支持MCP的LLM客户端无缝集成。
高质量语音合成：利用Chatterbox TTS模型，提供高品质的文本转语音服务，支持多种语调和声音风格。
声音克隆：支持使用参考音频进行声音克隆，定制独特的语音输出。
音韵控制：提供可调节的语音风格夸张程度和配置权重，实现更自然的语音表达。
灵活的音频播放：允许LLM客户端通过系统默认播放器播放生成的或现有的音频文件，并支持音量控制。
安全与管理：自动管理生成的临时音频文件，并具备路径验证和清理功能，确保系统安全。
双模式操作：除了MCP服务器模式，也支持作为独立的HTTP API服务器运行，提供ElevenLabs兼容的TTS接口。

安装步骤

该服务器使用Node.js开发，并依赖Python环境进行TTS模型的运行。首次启动时会自动安装Python依赖。

安装Node.js：确保您的系统已安装Node.js 16或更高版本。

全局安装包：打开终端或命令行工具，运行以下命令进行全局安装：

npm install -g local-voice-mcp

或者如果您希望从源代码安装，请先克隆仓库，然后运行：

git clone https://github.com/CodeCraftersLLC/local-voice-mcp.git
cd local-voice-mcp
npm install
npm run build

Python环境：系统需要Python 3.8+、PyTorch和Chatterbox TTS。服务器在首次运行时会自动设置Python环境并安装所需依赖。

MCP客户端配置

MCP服务器专为MCP客户端设计。您需要将以下配置添加到您的MCP客户端配置文件中（例如，Cursor编辑器的'config.json'），以便客户端能够发现并连接到本地语音MCP服务器。

{
  "mcpServers": {
    "local-voice-mcp": {
      // 用于启动Local Voice MCP服务器的命令
      "command": "local-voice-mcp-server", 
      // 传递给启动命令的参数，此处为空数组表示无额外参数
      "args": [], 
      // 环境变量，可用于定制TTS行为。以下是常用选项及示例：
      "env": {
        // "USE_MALE_VOICE": "true", // 设置为 "true" 可使用默认的男性声音，优先级低于自定义参考音频
        // "CHATTERBOX_EXAGGERATION": "0.5", // 调整语音风格夸张程度（浮点数，0.0-2.0，默认 0.2）
        // "CHATTERBOX_CFG_WEIGHT": "1.2", // 调整配置权重（浮点数，0.0-5.0，默认 1.0）
        // "CHATTERBOX_MAX_CHARACTERS": "2000", // 设置文本输入的最大字符数（整数，默认 2000）
        // "CHATTERBOX_PLAYBACK_VOLUME": "75", // 设置默认音频播放音量百分比（整数，0-100，默认 50）
        // "CHATTERBOX_REFERENCE_AUDIO": "/Users/yourname/Music/my-voice.wav" // 指定用于声音克隆的参考音频文件路径
      }
    }
  }
}

配置说明：

'mcpServers.local-voice-mcp.command': 指定启动本地语音MCP服务器的可执行命令。
'mcpServers.local-voice-mcp.args': 指定传递给启动命令的额外参数。
'mcpServers.local-voice-mcp.env': 允许设置影响服务器行为的环境变量。
- 'USE_MALE_VOICE': 当没有自定义参考音频时，设置为'"true"'将使用默认的男性声音，设置为'"false"'（默认值）将使用捆绑的女性声音。
- 'CHATTERBOX_EXAGGERATION': 设置语音风格的夸张程度，接受0.0到2.0之间的浮点数。
- 'CHATTERBOX_CFG_WEIGHT': 设置TTS模型的配置权重，接受0.0到5.0之间的浮点数。
- 'CHATTERBOX_MAX_CHARACTERS': 设置文本转语音输入文本的最大字符数，防止过长文本导致性能问题。
- 'CHATTERBOX_PLAYBACK_VOLUME': 设置默认的音频播放音量，接受0到100之间的整数百分比。
- 'CHATTERBOX_REFERENCE_AUDIO': 指定一个音频文件的完整路径，用于语音克隆。该文件可以是系统中的任意可访问音频。

基本使用方法

配置完成后，请重启您的MCP客户端。之后，您可以通过客户端的AI聊天界面或工具调用功能与本地语音MCP服务器进行交互。

可用工具：

'synthesize_text':
- 功能: 将文本转换为语音。
- 参数:
  - 'text' (必填，字符串): 要合成的文本。
  - 'referenceAudio' (可选，字符串): 用于声音克隆的参考音频文件路径。
  - 'exaggeration' (可选，数字): 语音风格夸张程度 (0-2)。
  - 'cfg_weight' (可选，数字): 配置权重 (0-5)。
- 示例: 在MCP客户端中输入类似 "使用'synthesize_text'工具合成文本 '您好，这是语音合成测试。'"。
'play_audio':
- 功能: 使用系统默认播放器播放指定的音频文件。
- 参数:
  - 'audioFile' (必填，字符串): 要播放的音频文件路径（通常是'synthesize_text'工具返回的路径）。
  - 'volume' (可选，数字): 播放音量百分比 (0-100)。
  - 'deleteAfterPlay' (可选，布尔值): 播放完成后是否删除音频文件（默认：'false'）。
- 示例: 在MCP客户端中输入类似 "播放刚生成的音频文件，音量设置为75%"。
'tts_status':
- 功能: 获取TTS服务的当前状态和能力信息。
- 参数: 无。
- 示例: 在MCP客户端中输入类似 "查询语音合成服务的状态"。

关键词

项目简介

主要功能点

安装步骤

MCP客户端配置

基本使用方法

信息