MCP TTS 服务器

基于模型上下文协议（MCP）框架构建的多功能TTS（文本转语音）服务器。该服务器通过统一接口提供对多个TTS引擎的访问：

1. Kokoro TTS - 高质量本地TTS引擎
2. OpenAI TTS - 基于云的TTS，通过OpenAI的API实现

功能

• 🌐 在一个统一的服务器中集成多个TTS引擎
• 🎧 实时流式音频播放
• 🔄 支持MCP协议，与Claude和其他大型语言模型无缝集成
• 🎛️ 可配置的语音选择功能，适用于两个引擎
• 💬 支持通过自然语言指令进行语音定制（OpenAI）
• ⚡ 对两个TTS引擎的速度调整
• 🛑 播放控制，包括停止音频和清空队列

安装

先决条件

• Python 3.10或更高版本
• uv 包管理器
• OpenAI API密钥（用于OpenAI TTS功能）

快速安装

# 克隆仓库
git clone https://github.com/kristofferv98/MCP_tts_server.git
cd MCP_tts_server

# 创建虚拟环境并安装依赖
uv venv
source .venv/bin/activate  # 在Windows上：.venv\Scripts\activate
uv pip install -e .

配置

根据提供的.env.example创建一个.env文件：

cp .env.example .env

编辑.env文件，添加您的OpenAI API密钥：

OPENAI_API_KEY=your_openai_api_key_here

与Claude Desktop集成

要使用此服务器与Claude Desktop：

1. 安装服务器：

   fastmcp install ./tts_mcp.py --name tts
   

2. 或者，您可以手动将服务器添加到Claude Desktop的配置文件中：

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

   在mcpServers部分添加以下条目：

   "kokoro_tts": {
     "command": "uv",
     "args": [
       "--directory",
       "/path/to/MCP_tts_server",
       "run",
       "tts_mcp.py"
     ]
   }
   

   使用uv的完整路径示例配置：

   "kokoro_tTts": {
     "command": "/Users/username/.local/bin/uv",
     "args": [
       "--directory",
       "/Users/username/Documents/MCP_Servers/MCP_tts_server",
       "run",
       "tts_mcp.py"
     ]
   }
   

MCP函数定义

服务器公开了以下MCP工具：

主TTS函数

{
  "description": "使用首选引擎将文本转换为语音，并将语音流传输给用户。AI的基础语音是Kokoro引擎，以保持AI个性的一致性。这个统一的功能提供了对Kokoro TTS（本地）和OpenAI TTS（云API）的访问。",
  "name": "tts",
  "parameters": {
    "properties": {
      "text": {"title": "文本", "type": "string"},
      "engine": {"default": "kokoro", "title": "引擎", "type": "string"},
      "speed": {"default": 1, "title": "速度", "type": "number"},
      "voice": {"default": "", "title": "语音", "type": "string"},
      "instructions": {"default": "", "title": "指令", "type": "string"}
    },
    "required": ["text"]
  }
}

参数：

• text（必需）：要转换为语音的文本
• engine（可选）：使用的TTS引擎 - "kokoro"（默认，本地）或"openai"（云）
• speed（可选）：播放速度（典型值为0.8-1.5）
• voice（可选）：使用的语音名称（特定于引擎）
• instructions（可选）：针对OpenAI TTS的语音定制指令

停止播放函数

{
  "description": "停止当前正在播放的音频（如果有），并清除队列中的所有待处理TTS请求。依赖后台工作者检测取消信号。",
  "name": "tts_stop_playback_and_clear_queue",
  "parameters": {
    "properties": {}
  }
}

语音示例函数

{
  "description": "提供基于研究的有效语音指令示例，适用于OpenAI TTS。",
  "name": "tts_examples",
  "parameters": {
    "properties": {
      "category": {"default": "general", "title": "类别", "type": "string"}
    }
  }
}

类别：

• general
• accents
• characters
• emotions
• narration

获取TTS指令函数

{
  "description": "通过调用get_voice_info获取TTS指令。",
  "name": "get_tts_instructions",
  "parameters": {
    "properties": {}
  }
}

直接使用

主要的使用方式是通过Claude Desktop或其他支持MCP的集成，如上所述。然而，您也可以直接运行服务器进行测试目的：

# 使用uv环境管理器运行
uv run python tts_mcp.py

# 或使用仅限Kokoro的简化版本
uv run python simple_tts_mcp.py

这将启动MCP服务器，使其可用于连接。

可用语音

Kokoro TTS

• 默认语音：af_heart

OpenAI TTS

• 可用语音：alloy, ash, ballad, coral, echo, fable, onyx, nova, sage, shimmer
• 默认模型：gpt-4o-mini-tts

开发和测试

在开发期间进行本地测试：

fastmcp dev ./tts_mcp.py

这将启动MCP Inspector界面，在那里您可以测试服务器的功能。

实现细节

服务器使用FastMCP实现，并遵循MCP服务器开发的最佳实践：

• 统一接口：单个函数支持Kokoro和OpenAI引擎
• 流式支持：尽可能直接向客户端流式传输音频
• 备用机制：当无法流式传输时，使用基于文件的播放
• 语音定制：支持OpenAI TTS的自然语言指令
• 生命周期管理：正确初始化和清理资源

故障排除

• 无音频输出：检查系统音频配置
• OpenAI TTS失败：验证您的API密钥有效且具有TTS访问权限
• 找不到服务器：确保MCP服务器已正确注册到您的MCP主机

许可证

本项目根据Apache许可证2.0发布 - 详情见LICENSE文件。

贡献

欢迎贡献！请随时提交Pull Request。