MCP TTS Server

MCP TTS 服务

基于 Model Context Protocol（MCP）框架构建的多功能 TTS（文本转语音）服务。此服务通过统一接口提供多种 TTS 引擎：

1. Kokoro TTS - 高品质本地 TTS 引擎
2. OpenAI TTS - 通过 OpenAI API 提供的云端 TTS

功能

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

安装

先决条件

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

快速安装

# Clone the repository
git clone https://github.com/kristofferv98/MCP_tts_server.git
cd MCP_tts_server

# Create a virtual environment and install dependencies
uv venv
source .venv/bin/activate  # On 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_tts": {
     "command": "/Users/username/.local/bin/uv",
     "args": [
       "--directory",
       "/Users/username/Documents/MCP_Servers/MCP_tts_server",
       "run",
       "tts_mcp.py"
     ]
   }
   

MCP 函数定义

此服务提供以下 MCP 工具：

主要 TTS 函数

{
  "description": "Convert text to speech using the preferred engine and streams the speech to the user. The base voice for the AI is the Kokoro engine, to keep AI's personality consistent. This unified function provides access to both Kokoro TTS (local) and OpenAI TTS (cloud API).",
  "name": "tts",
  "parameters": {
    "properties": {
      "text": {"title": "Text", "type": "string"},
      "engine": {"default": "kokoro", "title": "Engine", "type": "string"},
      "speed": {"default": 1, "title": "Speed", "type": "number"},
      "voice": {"default": "", "title": "Voice", "type": "string"},
      "instructions": {"default": "", "title": "Instructions", "type": "string"}
    },
    "required": ["text"]
  }
}

参数：

• text（必需）：要转换为语音的文本
• engine（可选）：要使用的 TTS 引擎——"kokoro"（默认，本地）或 "openai"（云端）
• speed（可选）：播放速度（通常为 0.8-1.5）
• voice（可选）：要使用的语音名称（因引擎而异）
• instructions（可选）：用于自定义 OpenAI TTS 语音的指令

停止播放函数

{
  "description": "Stops the currently playing audio (if any) and clears all pending TTS requests from the queue. Relies on the background worker detecting the cancellation signal.",
  "name": "tts_stop_playback_and_clear_queue",
  "parameters": {
    "properties": {}
  }
}

语音示例函数

{
  "description": "Provides research-based examples of effective voice instructions for OpenAI TTS.",
  "name": "tts_examples",
  "parameters": {
    "properties": {
      "category": {"default": "general", "title": "Category", "type": "string"}
    }
  }
}

类别：

• 通用
• 口音
• 角色
• 情绪
• 旁白

获取 TTS 指令函数

{
  "description": "Fetches TTS instructions by calling get_voice_info.",
  "name": "get_tts_instructions",
  "parameters": {
    "properties": {}
  }
}

直接使用

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

# Run with the uv environment manager
uv run python tts_mcp.py

# Or use the simplified Kokoro-only version
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 License 2.0 许可，详情请参阅 LICENSE 文件。

贡献

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