Text to Speech

文本转语音 MCP 服务

让 AI 助手发声——在本地运行，无需 API 密钥、账户或云服务。

Text to Speech 是一个开源的 Model Context Protocol（MCP）服务，可让 AI 助手在用户的计算机上朗读文本。它使用主机操作系统已有的语音合成器，因此你要求它朗读的内容永远不会离开你的设备。

支持 Windows、macOS 和 Linux。一行命令即可安装：

uvx text-to-speech-mcp

该服务提供一个由模型控制的工具：

speak_text(text: string)

可用于朗读用户提供的文本、助手回答、无障碍工作流，或在 Agent 工作时播报进度。

为什么选择它

大多数文本转语音 MCP 服务都封装了云 API，这意味着需要账户、密钥、按字符计费，而且文本会离开设备。这个服务使用操作系统自带的语音引擎，因此可以离线运行、完全免费，并让文本留在本地——如果你的工作环境对数据去向有规定，这一点就很重要。

它还附带一个 Agent 旁白技能，让助手知道如何进行旁白，而不仅仅是知道自己能做到。

功能

• 默认通过平台内置的合成器进行本地播放：Windows SAPI、macOS say，或 Linux 上的 espeak-ng。
• 默认配置无需云 API 或 API 密钥。
• FIFO 播放：并发请求会按顺序逐一朗读。
• 工具调用会阻塞至完成：每次调用都会在音频播放结束后返回。
• 限制输入和队列大小，防止资源无限制增长。
• 默认在播放后删除临时生成的 WAV 文件。
• 通过官方 Python SDK 使用标准 MCP stdio 传输。
• 为高级用户提供可选的 Piper、Transformers MMS 和本地 HTTP 后端。

MCP 服务源代码采用 MIT License 开源。Windows SAPI 和 macOS say 命令是各自操作系统的专有组件，并非开源语音引擎。espeak-ng 则是采用独立许可证的开源软件。

要求

• Python 3.10 或更高版本。
• 支持 stdio MCP 服务的 MCP 客户端。
• 推荐使用 uv/uvx 安装基于软件包的 MCP 服务。

各平台零配置默认设置所需组件：

平台	合成	播放	额外安装
Windows 10/11	通过 PowerShell 使用 SAPI	System.Media.SoundPlayer	无
macOS	say	afplay	无
Linux / 其他 Unix	espeak-ng 或 espeak	aplay、paplay、play 或 ffplay	espeak-ng 和一种播放器

在 Debian 或 Ubuntu 上，通常需要：

sudo apt install espeak-ng alsa-utils

设置 TEXT_TO_SPEECH_BACKEND 或 TEXT_TO_SPEECH_PLAYER 可覆盖相应选项。如果缺少必需命令，服务会报告具体缺少的命令及安装方法，而不会静默失败。

安装

配置 MCP 客户端运行已发布到 PyPI 的软件包：

uvx text-to-speech-mcp

对于接受基于命令的服务配置的 MCP 客户端，请使用：

command = "uvx"
args = ["text-to-speech-mcp"]
startup_timeout_sec = 30
tool_timeout_sec = 300
enabled = true

有些客户端使用 TOML、JSON 或图形化设置页面。将 uvx text-to-speech-mcp 设为服务命令，并在修改配置后重启客户端。

从源代码安装

git clone https://github.com/Engr-FaizanAli/text-to-speech-mcp.git
cd text-to-speech-mcp
python -m pip install .

然后配置客户端直接运行 text-to-speech-mcp。

提示词示例

读取任意文本：

Use the Text to Speech tool to read aloud: The deployment completed successfully.

读取最终回答：

Use the Text to Speech tool to read your final response aloud before displaying it.

按顺序读取可见的中间进度更新：

Use the text_to_speech MCP server's speak_text tool for spoken progress updates.

For every meaningful intermediate update that you display to me:
1. Call speak_text with the exact update text you are about to display.
2. Wait for the call to finish before producing or speaking the next update.
3. Then display the same update in text.

Also call speak_text with the exact final answer before displaying it. Never
narrate hidden reasoning, chain-of-thought, secrets, credentials, raw tool
output, terminal logs, or source code unless I explicitly ask you to read that
content aloud. Do not invoke speech calls in parallel. If the tool is
unavailable, continue normally in text and report the failure once.

text_to_speech 部分是客户端侧服务名称的一个示例。客户端可能会显示不同的命名空间，但工具名称 speak_text 保持不变。

工具契约

字段	值
工具名称	speak_text
输入	text，必填字符串，长度为 1-50,000 个字符
结果	本地播放结束后的完成消息
顺序	先进先出，一次仅播放一项
队列上限	32 个待处理请求
使用内置后端时的网络使用情况	无

该工具在 MCP 下由模型控制。用户决定何时要求模型调用该工具，MCP 客户端也可能会显示工具调用，或要求用户批准。

隐私

使用任何内置后端时，文本会从 MCP 客户端传递到本地 Python 进程，然后传递给操作系统的语音组件。文本不会发送到本项目、外部 API 或云端 TTS 提供商。生成的 WAV 文件会写入系统临时目录（Windows 上为 %TEMP%，macOS 和 Linux 上为 /tmp）中的 text-to-speech-mcp 目录，并在播放后删除，除非设置了 TEXT_TO_SPEECH_KEEP_AUDIO=true。

http 后端是个例外：文本是否会离开本机完全取决于你配置的端点。

不要要求 AI 助手朗读机密、凭据、私钥、隐藏推理或敏感工具输出。

可选后端

默认情况下无需配置。TEXT_TO_SPEECH_BACKEND 未设置时，服务会选择与主机平台匹配的 sapi、say 或 espeak。

如需明确指定某个后端，或使用操作系统未内置的后端，请将 TEXT_TO_SPEECH_BACKEND 设置为 sapi、say、espeak、piper、transformers_mms 或 http。最后三种后端需要各自的本地模型、二进制文件、Python 依赖项或端点。若第一个后端失败，TEXT_TO_SPEECH_FALLBACK_BACKEND 用于指定要尝试的第二个后端。请参阅后端配置。

Agent 旁白技能

仅有语音工具并不能告诉助手何时或如何朗读。如果任由 Agent 自行发挥，它们可能会讲述隐藏推理、跳过你真正需要的内容，或是朗读改写后的内容，而不是屏幕上显示的内容。

skills/project-tts-responder/SKILL.md 是基于 speak_text 构建的现成旁白策略。将其复制到项目的 .claude/skills/ 目录中：

模式	行为
批量（默认）	在一轮结束时播放一次，涵盖所有可见更新以及最终回答
流式	更新出现时逐条朗读，适用于演示和操作演练
按需朗读	逐字朗读指定文件或文本块

它还处理了一些容易出错的情况：

• 在选择器打开之前朗读交互式问题。 交互式问题工具本身就是暂停点，其选项位于工具参数中，而非可见文本中。因此，任何要求“在选项可见后”朗读的规则，只有在用户已经作答后才会触发。这是旁白悄无声息地失效的最常见原因。
• 准确朗读屏幕上的内容，不作改写。
• 绝不朗读隐藏推理、机密、凭据或原始工具输出。
• 每轮仅调用一次播放，不并行播放，并明确定义调用失败时的行为。

请求音频时，该技能会生效。若要让项目朗读每个响应，请在该项目自己的 Agent 指令中说明，例如：“除非我选择退出，否则每个响应都使用批量模式进行旁白朗读。”

MCP 兼容性

• MCP 传输方式：stdio
• MCP 工具实现：官方 Python MCP SDK
• 注册表元数据：使用 2025-12-11 架构的 server.json
• 包注册表：PyPI
• 注册表所有权标记：本 README 中的 mcp-name 注释
• 注册表命名空间：io.github.Engr-FaizanAli/text-to-speech

许可证

MIT。请参阅 LICENSE。