语音 MCP 服务器

一个使用 Kokoro TTS 模型提供文本到语音功能的模型上下文协议服务器。

配置

服务器可以使用以下环境变量进行配置：

变量	描述	默认值	有效范围
MCP_DEFAULT_SPEECH_SPEED	文本到语音的默认语速倍增器	1.1	0.5 到 2.0
MCP_DEFAULT_VOICE	文本到语音的默认声音	af_bella	任何有效的声音 ID

在 Cursor 中：

{
  "mcpServers": {
    "speech": {
      "command": "npx",
      "args": [
        "-y",
        "speech-mcp-server"
      ],
      "env": {
        "MCP_DEFAULT_SPEECH_SPEED": 1.3,
        "MCP_DEFAULT_VOICE": "af_bella"
      }
    }
  }
}

特性

• 🎯 使用 Kokoro TTS 模型的高质量文本到语音转换
• 🗣️ 提供多种声音选项
• 🎛️ 可定制的语音参数（声音、语速）
• 🔌 符合 MCP 协议的接口
• 📦 易于安装和设置
• 🚀 无需 API 密钥

安装

# 使用 npm
npm install speech-mcp-server

# 使用 pnpm (推荐)
pnpm add speech-mcp-server

# 使用 yarn
yarn add speech-mcp-server

用法

运行服务器：

# 使用默认配置
npm start

# 使用自定义配置
MCP_DEFAULT_SPEECH_SPEED=1.5 MCP_DEFAULT_VOICE=af_bella npm start

服务器提供以下 MCP 工具：

• text_to_speech: 基础的文本到语音转换
• text_to_speech_with_options: 具有可定制语速的文本到语音转换
• list_voices: 列出所有可用的声音
• get_model_status: 检查 TTS 模型的初始化状态

开发

# 克隆仓库
git clone <your-repo-url>
cd speech-mcp-server

# 安装依赖
pnpm install

# 启动具有自动重载的开发服务器
pnpm dev

# 构建项目
pnpm build

# 运行 linting
pnpm lint

# 格式化代码
pnpm format

# 使用 MCP Inspector 进行测试
pnpm inspector

可用工具

1. text_to_speech

使用默认设置将文本转换为语音。

{
  "type": "request",
  "id": "1",
  "method": "call_tool",
  "params": {
    "name": "text_to_speech",
    "arguments": {
      "text": "Hello world",
      "voice": "af_bella"  // 可选
    }
  }
}

2. text_to_speech_with_options

使用可自定义的参数将文本转换为语音。

{
  "type": "request",
  "id": "1",
  "method": "call_tool",
  "params": {
    "name": "text_to_speech_with_options",
    "arguments": {
      "text": "Hello world",
      "voice": "af_bella",  // 可选
      "speed": 1.0,         // 可选 (0.5 到 2.0)
    }
  }
}

3. list_voices

列出所有可用于文本到语音的声音。

{
  "type": "request",
  "id": "1",
  "method": "list_voices",
  "params": {}
}

4. get_model_status

检查 TTS 模型初始化的当前状态。 这在首次启动服务器时特别有用，因为需要下载和初始化模型。

{
  "type": "request",
  "id": "1",
  "method": "call_tool",
  "params": {
    "name": "get_model_status",
    "arguments": {}
  }
}

响应示例：

{
  "content": [{
    "type": "text",
    "text": "Model status: initializing (5s elapsed)"
  }]
}

可能的状态值：

• uninitialized: 模型初始化尚未开始
• initializing: 模型正在下载和初始化
• ready: 模型已准备好使用
• error: 初始化期间发生错误

测试

您可以使用 MCP Inspector 或发送原始 JSON 消息来测试服务器：

# 列出可用工具
echo '{"type":"request","id":"1","method":"list_tools","params":{}}' | node dist/index.js

# 列出可用声音
echo '{"type":"request","id":"2","method":"list_voices","params":{}}' | node dist/index.js

# 将文本转换为语音
echo '{"type":"request","id":"3","method":"call_tool","params":{"name":"text_to_speech","arguments":{"text":"Hello world","voice":"af_bella"}}}' | node dist/index.js

与 Claude Desktop 集成

要将此服务器与 Claude Desktop 一起使用，请将以下内容添加到您的 Claude Desktop 配置文件 (~/Library/Application Support/Claude/claude_desktop_config.json)：

{
  "servers": {
    "speech": {
      "command": "npx",
      "args": ["@decodershq/speech-mcp-server"]
    }
  }
}

贡献

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

许可证

MIT 许可证 - 有关详细信息，请参阅 LICENSE 文件。

故障排除

模型初始化问题

服务器会在启动时自动尝试下载和初始化 TTS 模型。 如果您遇到初始化错误：

1. 服务器将自动重试最多 3 次，并在尝试之间进行清理
2. 使用 get_model_status 工具来监控初始化进度和任何错误
3. 如果在所有重试后初始化失败，请尝试手动删除模型文件：

# 删除模型文件 (MacOS/Linux)
rm -rf ~/.npm/_npx/**/node_modules/@huggingface/transformers/.cache/onnx-community/Kokoro-82M-v1.0-ONNX/onnx/model_quantized.onnx
rm -rf ~/.cache/huggingface/transformers/onnx-community/Kokoro-82M-v1.0-ONNX/onnx/model_quantized.onnx

# 然后重启服务器
npm start

get_model_status 工具现在将在其响应中包含重试信息：

{
  "content": [{
    "type": "text",
    "text": "Model status: initializing (5s elapsed, retry 1/3)"
  }]
}