AI导哈

文本转语音服务器

tts-mcp是一个基于Google Cloud Text-to-Speech API的多客户端配置文件驱动的文本转语音服务器，允许为每个应用或客户端定义独立的语音配置。

  • by that-lucas
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 that-lucas/tts-mcp

使用说明

tts-mcp

配置文件驱动的MCP服务器 谷歌云文本转语音：为每个应用程序/客户端定义一个配置文件，以便每个工具始终以正确的声音和设置说话。

向任何MCP客户端公开三个工具：

  • tts_speak --将文本合成为音频并自动播放
  • tts_doctor --对身份验证、配置文件和播放运行诊断
  • tts_stop --停止当前播放的任何音频

每个配置文件都锁定了语音、语言、型号和格式——LLM只能控制文本内容、语速和音高。

安装

pip install tts-mcp

或与 uvx （无需安装）：

uvx tts-mcp --help

先决条件

  • Python 3.11+
  • A. 谷歌云项目 随着 云文本到速度API 启用
  • 谷歌提供了一个慷慨的免费等级——高达 400万字符/月 （大致 84小时 标准和WaveNet语音的正常语速的英语语音），以及 100万字符/月 （大致 21小时)适用于Neural2、Polyglot、Chirp 3:HD和Studio语音，足以满足大多数个人使用。看 TTS定价 了解详情。
  • 谷歌云CLI (gcloud)用于身份验证
  • macOS使用 afplay 默认情况下用于播放（可通过配置文件配置）

设置

1.使用Google Cloud进行身份验证

gcloud auth application-default login
gcloud auth application-default set-quota-project YOUR_PROJECT_ID

这将凭据存储在 ~/.config/gcloud/application_default_credentials.json，TTS客户端会自动发现。不需要环境变量。

2.创建配置文件

tts-mcp --init
${EDITOR:-vi} ~/.config/tts-mcp/profiles.json

这将在以下位置创建启动器配置 ~/.config/tts-mcp/profiles.json 其中包含每个Google TTS语音层的示例配置文件。编辑它以选择您的语音、格式和播放设置。

服务器会自动找到配置文件——否 --profiles 普通情况下需要的标志。搜索顺序为：

  1. --profiles 旗帜或 TTS_MCP_PROFILES_PATH env-var（显式重写）
  2. ~/.config/tts-mcp/profiles.json （XDG标准——由 tts-mcp --init)

MCP客户端设置

运行后 tts-mcp --init，没有 --profiles 需要标志——服务器会发现 ~/.config/tts-mcp/profiles.json 自动。请通过 --profile 选择每个客户端使用的配置文件。

克劳德代码

claude mcp add --transport stdio --scope user \
  speech -- tts-mcp --profile claude

开源代码

编辑 ~/.config/opencode/opencode.jsonc:

{
  "mcp": {
    "speech": {
      "type": "local",
      "command": ["tts-mcp", "--profile", "opencode"],
      "enabled": true,
      "timeout": 120000
    }
  }
}

Codex CLI

编辑 ~/.codex/config.toml:

[mcp_servers.speech]
command = "tts-mcp"
args = ["--profile", "codex"]

使用uvx（无全局安装）

任何客户端配置都可以使用 uvx 而不是全局安装：

{
  "command": "uvx",
  "args": ["--update", "tts-mcp", "--profile", "opencode"]
}

用法

在任何启用MCP的客户端中，自然提示：

  • Summarize this and read it aloud.
  • Stop talking.

工具名称可能以客户端为前缀（例如。 speech_tts_speak, speech_tts_stop).

CLI参考

该软件包安装了四个命令。每个支持 --help 了解全部细节。 对于正常使用，您只需要 tts-mcp --init 加上上面的MCP客户端设置；以下命令主要用于诊断或手动测试。

tts-mcp --MCP服务器和管理

tts-mcp --init              # create starter config at ~/.config/tts-mcp/profiles.json
tts-mcp --init --force      # overwrite existing config
tts-mcp --doctor            # diagnostics: auth, profile, voice, player
tts-mcp --profile casual    # start MCP server with a specific profile

默认值：

  • --profiles: TTS_MCP_PROFILES_PATH env变量或 "" （然后自动发现运行）
  • --profile: TTS_MCP_PROFILE_NAME env变量或 "" （那么 default_profile 使用）
  • --doctor, --init, --force: false

tts-speak --将文本合成为音频

tts-speak --text "Hello world" --voice en-US-Chirp3-HD-Fenrir --format wav --out hello.wav
tts-speak --text-file notes.txt --voice en-US-Neural2-D --format mp3 --out notes.mp3
tts-speak --ssml --text "<speak>Hello <break time='500ms'/> world</speak>" --out ssml.wav
echo "Piped text" | tts-speak --voice en-US-Casual-K --out piped.ogg

选项： --text, --text-file, --voice, --language, --model, --format （mp3/ogg/wav）， --speaking-rate, --pitch, --out, --usage-log.

默认值：

  • --voice: ""
  • --language: en-US
  • --model: ""
  • --format: mp3
  • --speaking-rate: 1.0
  • --pitch: 0.0
  • --out: "" （自动生成 YYYYMMDD-HHMMSS-ms.ext 在当前目录中，本地时区）
  • --usage-log: usage_log.csv
  • 输入：如果两者都没有 --text 也不 --text-file 如果提供，CLI将读取管道stdin或提示输入文本

tts-voices --列出可用声音

tts-voices                              # list en-US voices (default language)
tts-voices --language en-US             # filter by language
tts-voices --language en-US --family Chirp3   # filter by family
tts-voices --limit 5                    # limit results

默认值：

  • --language: en-US
  • --family: "" （无家庭过滤器）
  • --limit: 0 （无限制）

tts-batch --为多个语音生成样本

tts-batch --text-file test.txt --out-dir ./samples
tts-batch --text-file test.txt --families Chirp3,Neural2 --language en-US --format wav
tts-batch --text-file test.txt --limit 3   # first 3 matching voices only

默认值：

  • --families: "" （无家庭过滤器）
  • --language: en-US
  • --format: mp3
  • --out-dir: ./out
  • --speaking-rate: 1.0
  • --pitch: 0.0
  • --limit: 0 （所有匹配的声音）
  • --text-file：必填

配置文件系统

配置文件在JSON文件中定义（请参见 profiles.example.json):

{
  "default_profile": "opencode",
  "profiles": {
    "opencode": {
      "voice": "en-US-Chirp3-HD-Fenrir",
      "language": "en-US",
      "model": "models/chirp3-hd",
      "format": "wav",
      "speaking_rate": 1.0,
      "pitch": 0.0,
      "output_dir": "~/.local/share/tts-mcp/out",
      "usage_log": "~/.local/share/tts-mcp/usage_log.csv",
      "autoplay": true,
      "player_command": ["afplay", "{file}"]
    }
  }
}

每个配置文件锁定： voice, language, model, format, output_dir, usage_log, autoplay，以及 player_command.只有 speaking_rate 和 pitch 可以在每次工具调用时被覆盖。

故障排除

  • 身份验证错误 --奔跑 gcloud auth application-default login，或确认 GOOGLE_APPLICATION_CREDENTIALS 已设置。
  • 无音频 --验证玩家二进制文件（例如。 afplay)存在或改变 player_command 在您的个人资料中。
  • 刀具超时 --播放是非阻塞的，但如果超时持续存在，请增加客户端的 tool_timeout.
  • 运行诊断程序 — tts-mcp --doctor 检查身份验证、个人资料、语音和玩家。

发展

git clone git@github.com:that-lucas/tts-mcp.git
cd tts-mcp
make setup    # creates venv, installs package + dev deps, sets git hooks
make test     # run pytest
make lint     # run ruff check + format check

看 贡献.md 了解详情。

许可证

麻省理工学院

相关 MCP