MCP TTS 服务器

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

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

功能特性

• 🌐 一个统一的服务器中包含多个 TTS 引擎
• 🎧 实时流式音频播放
• 🔄 MCP 协议支持，可与 Claude 和其他 LLM 无缝集成
• 🎛️ 可配置的语音选择，适用于两个引擎
• 💬 支持通过自然语言指令进行语音自定义 (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_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": "使用首选引擎将文本转换为语音，并将语音流式传输给用户。AI 的基本声音是 Kokoro 引擎，以保持 AI 的个性一致。此统一函数提供对 Kokoro TTS（本地）和 OpenAI TTS（云 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": "停止当前正在播放的音频（如果有），并清除队列中所有待处理的 TTS 请求。依赖于检测取消信号的后台工作程序。",
  "name": "tts_stop_playback_and_clear_queue",
  "parameters": {
    "properties": {}
  }
}

语音示例函数

{
  "description": "提供基于研究的有效语音指令示例，用于 OpenAI TTS。",
  "name": "tts_examples",
  "parameters": {
    "properties": {
      "category": {"default": "general", "title": "Category", "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

这将启动 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。