mcp-tts

mcp-tts

TTS（文本转语音）MCP 服务

这是什么？🤔

为 Claude Desktop 和 Cursor IDE 等工具添加文本转语音功能。

它会注册现有的 TTS 工具；当 voice-say 可在 PATH 中找到时，还会注册 voice_tts：

• say_tts
• voice_tts（如可用）
• elevenlabs_tts
• google_tts
• openai_tts

say_tts

使用 macOS 的 say 二进制程序，通过内置系统语音朗读文本

voice_tts

使用来自 Voice 的本地 voice-say CLI，通过 MLX 运行 Qwen3-TTS。Voice 无需 API 密钥，文本和音频也始终保留在 Mac 上。每次调用都会重新加载模型，因此启动通常需要数秒；建议用于摘要和通知，而非时间紧迫的警报。

仅当 voice-say 可在 PATH 中找到时才会注册此工具。可选参数：

• voice：预设语音 Ryan 或 Aiden
• tier：small 使用速度更快的 0.6B 合成模型；large 使用质量更高的 1.7B 合成模型
• style：自由文本形式的表达指导
• describe：自由文本形式的语音设计；会强制使用 1.7B 模型，且不能与 voice 同时使用

Voice 会直接播放音频，不支持 --output-dir；使用 --no-play 时，如果不启动 voice-say，调用就会失败。

警告

Voice 仓库目前为私有仓库，之后不久将公开发布，因此目前需要访问权限才能打开链接。

elevenlabs_tts

使用 ElevenLabs 文本转语音 API，通过高级 AI 语音朗读文本

google_tts

使用 Google 的 Gemini TTS 模型，通过 30 种高品质语音朗读文本。可用语音包括：

Achernar、Achird、Algenib、Algieba、Alnilam、Aoede、Autonoe、Callirrhoe、Charon、Despina、Enceladus、Erinome、Fenrir、Gacrux、Iapetus、Kore、Laomedeia、Leda、Orus、Puck、Pulcherrima、Rasalgethi、Sadachbia、Sadaltager、Schedar、Sulafat、Umbriel、Vindemiatrix、Zephyr、Zubenelgenubi

openai_tts

使用 OpenAI 的 Text-to-Speech API，通过 10 种自然悦耳的声音朗读文本：

• alloy（温暖、善于对话、现代）
• ash（自信、坚定、略带质感）
• ballad（温柔、悦耳、略带抒情）
• coral（愉快、清新、活泼）
• echo（中性、平静、平和）
• fable（讲故事般、生动）
• nova（清晰、精准、略显正式）
• onyx（低沉、权威、浑厚）
• sage（舒缓、善解人意、令人安心）
• shimmer（明亮、生动、俏皮）
• verse（多才多艺、富有表现力）

支持三种质量模型：

• gpt-4o-mini-tts - 默认，兼顾质量与速度
• tts-1 - 标准质量，生成速度更快
• tts-1-hd - 高清音频，优质音质

附加功能：

• 支持 0.25x 至 4.0x 的语速调节（默认：1.0x）
• 可通过参数或 OPENAI_TTS_INSTRUCTIONS 环境变量设置自定义语音指令（例如，“以愉快、积极的语气说话”）

配置

顺序与并发 TTS

默认情况下，TTS 服务会强制按顺序执行语音操作——同一时间只能播放一个 TTS 请求的音频。这样可以防止多个 Agent 同时说话，造成难以听懂的混乱。后续请求会排队等待，直到当前语音播放完成。

多实例保护：互斥锁在单个 MCP 服务进程内以及多个 Claude Desktop 实例之间均有效。运行多个 Claude Desktop 终端时，它们会通过系统级文件锁进行协调，以防止语音重叠。

如需允许并发执行 TTS 操作（同时播放多段语音）：

环境变量：

export MCP_TTS_ALLOW_CONCURRENT=true

命令行标志：

mcp-tts --sequential-tts=false

**注意：**并发 TTS 可能导致音频重叠，难以听清。仅在明确需要同时运行多个 TTS 操作时使用此选项。

禁用“Speaking:”输出

默认情况下，TTS 工具会在语音播放完成后返回类似“Speaking: [text]”的消息。这可能会干扰大模型的响应。如需禁用此输出：

环境变量：

export MCP_TTS_SUPPRESS_SPEAKING_OUTPUT=true

命令行标志：

mcp-tts --suppress-speaking-output

启用后，工具会返回“Speech completed”，而不是重复输出朗读的文本。

将音频保存到磁盘

将 TTS 音频输出保存到文件，而不是播放音频（或在播放的同时保存）：

环境变量：

export MCP_TTS_OUTPUT_DIR=/path/to/audio    # Save audio files to this directory
export MCP_TTS_NO_PLAY=true                  # Skip playback, only save (optional)

命令行标志：

mcp-tts --output-dir /path/to/audio          # Save and play
mcp-tts --output-dir /path/to/audio --no-play  # Save only, no playback

文件将以唯一名称保存：tts_{timestamp}_{hash}.{ext}

提供方	格式
macOS say	AIFF
Voice	仅播放
ElevenLabs	MP3
Google TTS	WAV
OpenAI TTS	MP3

开始使用

安装

go install github.com/blacktop/mcp-tts@latest

❱ mcp-tts --help

TTS (text-to-speech) MCP Server.

Provides multiple text-to-speech services via MCP protocol:

• say_tts - Uses macOS built-in 'say' command (macOS only)
• voice_tts - Uses local Qwen3-TTS through voice-say (when available on PATH)
• elevenlabs_tts - Uses ElevenLabs API for high-quality speech synthesis
• google_tts - Uses Google's Gemini TTS models for natural speech
• openai_tts - Uses OpenAI's TTS API with various voice options

Each tool supports different voices, rates, and configuration options.
Requires appropriate API keys for cloud-based services.

Designed to be used with the MCP (Model Context Protocol).

Usage:
  mcp-tts [flags]

Flags:
  -h, --help                       help for mcp-tts
      --no-play                    Skip playback, only save (requires --output-dir)
      --output-dir string          Save audio files to directory (env: MCP_TTS_OUTPUT_DIR)
      --sequential-tts             Enforce sequential TTS (prevent concurrent speech) (default true)
      --suppress-speaking-output   Suppress 'Speaking:' text output
  -v, --verbose                    Enable verbose debug logging

配置

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "say": {
      "command": "mcp-tts",
      "env": {
        "ELEVENLABS_API_KEY": "********",
        "ELEVENLABS_VOICE_ID": "EXAVITQu4vr4xnSDxMaL",
        "GOOGLE_AI_API_KEY": "********",
        "OPENAI_API_KEY": "********",
        "OPENAI_TTS_INSTRUCTIONS": "Speak in a cheerful and positive tone",
        "MCP_TTS_SUPPRESS_SPEAKING_OUTPUT": "true",
        "MCP_TTS_ALLOW_CONCURRENT": "false"
      }
    }
  }
}

Claude Code

claude mcp add say \
  -e GOOGLE_AI_API_KEY=your_key \
  -e ELEVENLABS_API_KEY=your_key \
  -e OPENAI_API_KEY=your_key \
  -- mcp-tts

Codex CLI

codex mcp add say \
  --env GOOGLE_AI_API_KEY=your_key \
  --env ELEVENLABS_API_KEY=your_key \
  --env OPENAI_API_KEY=your_key \
  -- mcp-tts

Gemini CLI

gemini mcp add say mcp-tts \
  -e GOOGLE_AI_API_KEY=your_key \
  -e ELEVENLABS_API_KEY=your_key \
  -e OPENAI_API_KEY=your_key

或者手动添加到 ~/.gemini/settings.json（或项目根目录下的 .gemini/settings.json）：

{
  "mcpServers": {
    "say": {
      "command": ["mcp-tts"],
      "env": {
        "GOOGLE_AI_API_KEY": "..."
      }
    }
  }
}

环境变量

• ELEVENLABS_API_KEY：你的 ElevenLabs API 密钥（elevenlabs_tts 必需）
• ELEVENLABS_VOICE_ID：ElevenLabs 语音 ID（可选，默认为预制的 “Sarah” 语音 EXAVITQu4vr4xnSDxMaL）。免费套餐 API 密钥只能使用预制语音，语音库（社区／专业）中的语音会返回 402 paid_plan_required。
• GOOGLE_AI_API_KEY 或 GEMINI_API_KEY：你的 Google AI API 密钥（google_tts 必需）
• OPENAI_API_KEY：你的 OpenAI API 密钥（openai_tts 必需）
• OPENAI_TTS_INSTRUCTIONS：OpenAI TTS 的自定义语音指令（可选，例如“用欢快、积极的语气说话”）
• MCP_TTS_SUPPRESS_SPEAKING_OUTPUT：设为 "true" 可隐藏 "Speaking:" 输出（可选）
• MCP_TTS_ALLOW_CONCURRENT：设为 "true" 可允许并发 TTS 操作（可选，默认按顺序执行）
• MCP_TTS_OUTPUT_DIR：用于保存音频文件的目录（可选）
• MCP_TTS_NO_PLAY：设为 "true" 可在保存时跳过播放（可选，需设置 MCP_TTS_OUTPUT_DIR）
• MCP_TTS_ELICIT：设为 "true" 可启用交互式询问提示（也可使用 --elicit；可选，默认关闭）。关闭时，工具会使用明确参数／默认值，不会发起询问——推荐用于 Agent。

测试

测试 macOS TTS

❱ cat test/say.json | go run main.go --verbose

2025/03/23 22:41:49 INFO Starting MCP server name="Say TTS Service" version=1.0.0
2025/03/23 22:41:49 DEBU Say tool called request="{Request:{Method:tools/call Params:{Meta:<nil>}} Params:{Name:say_tts Arguments:map[text:Hello, world!] Meta:<nil>}}"
2025/03/23 22:41:49 DEBU Executing say command args="[--rate 200 Hello, world!]"
2025/03/23 22:41:49 INFO Speaking text text="Hello, world!"

{"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"Speaking: Hello, world!"}]}}

测试 Google TTS

❱ cat test/google_tts.json | go run main.go --verbose

2025/05/23 18:26:45 INFO Starting MCP server name="Say TTS Service" version=""
2025/05/23 18:26:45 DEBU Google TTS tool called request="{...}"
2025/05/23 18:26:45 DEBU Generating TTS audio model=gemini-3.1-flash-tts-preview voice=Kore text="Hello! This is a test of Google's TTS API. How does it sound?"
2025/05/23 18:26:49 INFO Playing TTS audio via beep speaker bytes=181006
2025/05/23 18:26:53 INFO Speaking via Google TTS text="Hello! This is a test of Google's TTS API. How does it sound?" voice=Kore

{"jsonrpc":"2.0","id":4,"result":{"content":[{"type":"text","text":"Speaking: Hello! This is a test of Google's TTS API. How does it sound? (via Google TTS with voice Kore)"}]}}

测试 OpenAI TTS

❱ cat test/openai_tts.json | go run main.go --verbose

2025/05/23 19:15:32 INFO Starting MCP server name="Say TTS Service" version=""
2025/05/23 19:15:32 DEBU OpenAI TTS tool called request="{...}"
2025/05/23 19:15:32 DEBU Generating OpenAI TTS audio model=tts-1 voice=nova speed=1.2 text="Hello! This is a test of OpenAI's text-to-speech API. I'm using the nova voice at 1.2x speed."
2025/05/23 19:15:34 DEBU Decoding MP3 stream from OpenAI
2025/05/23 19:15:34 DEBU Initializing speaker for OpenAI TTS sampleRate=22050
2025/05/23 19:15:36 INFO Speaking text via OpenAI TTS text="Hello! This is a test of OpenAI's text-to-speech API. I'm using the nova voice at 1.2x speed." voice=nova model=tts-1 speed=1.2

{"jsonrpc":"2.0","id":5,"result":{"content":[{"type":"text","text":"Speaking: Hello! This is a test of OpenAI's text-to-speech API. I'm using the nova voice at 1.2x speed. (via OpenAI TTS with voice nova)"}]}}

使用多个 TTS 请求测试互斥锁行为

# Sequential mode (default) - speeches play one after another
cat test/sequential.json | go run main.go --verbose

# Concurrent mode - allows overlapping speech  
cat test/sequential.json | go run main.go --verbose --sequential-tts=false

技能：speak

此仓库包含一个 speak 技能，可使用 TTS 自动大声播报计划、问题和摘要。该技能默认使用主机的 macOS say 语音，也可按项目或消息类型分配不同的语音，让你即使在另一个房间也能辨别正在播报的内容。

技能遵循 Agent Skills 开放标准，可用于 Claude Code、Codex CLI 和 Gemini CLI。

安装技能

skills.sh

npx skills add https://github.com/blacktop/mcp-tts --skill speak

Claude Code

通过插件市场（推荐）：

claude plugin marketplace add blacktop/mcp-tts
claude plugin install speak@mcp-tts

或手动安装：

mkdir -p ~/.claude/skills
git clone https://github.com/blacktop/mcp-tts.git /tmp/mcp-tts
cp -r /tmp/mcp-tts/skill ~/.claude/skills/speak

现在即可使用该技能。Claude 会在适用时自动使用它，也可以通过 /speak 直接调用。

Codex CLI

使用 skill-installer（在 Codex 会话中）：

$skill-installer install the speak skill from https://github.com/blacktop/mcp-tts --path skill

或手动安装：

mkdir -p ~/.codex/skills
git clone https://github.com/blacktop/mcp-tts.git /tmp/mcp-tts
cp -r /tmp/mcp-tts/skill ~/.codex/skills/speak

安装后重启 Codex。

Gemini CLI

Gemini CLI 使用扩展来打包技能。将此仓库安装为扩展：

gemini extensions install https://github.com/blacktop/mcp-tts.git

这会安装 speak 技能。

或手动安装（仅安装技能）：

mkdir -p ~/.gemini/skills
git clone https://github.com/blacktop/mcp-tts.git /tmp/mcp-tts
cp -r /tmp/mcp-tts/skill ~/.gemini/skills/speak

**注意：**Gemini CLI 技能仍处于实验阶段。请通过 /settings → 搜索 "Skills" → 开启开关来启用。

共享技能目录（可选）

如需在所有 Agent 之间共用一份副本，请运行安装脚本：

git clone https://github.com/blacktop/mcp-tts.git
cd mcp-tts
./install-skill.sh

这会将技能复制到 ~/.agents/skills/speak，并为 Claude Code、Codex CLI 和 Gemini CLI 创建符号链接。

验证安装

Agent	命令
Claude Code	询问“有哪些可用技能？”或输入 /speak
Codex CLI	重启后自动加载技能
Gemini CLI	运行 gemini extensions list，或在 /settings 中查看技能

工作原理

在以下情况后应选择此技能：

• 规划完成 - 计划/待办列表定稿时
• 问题已解决 - 错误修复或问题解决时
• 已生成摘要 - 完成重要任务时
• 长时间操作状态发生变化 - 构建、测试、部署、发布、研究或监控阶段完成或失败时
• 需要人工介入 - 进度因等待审批、身份验证、手动操作或重试次数耗尽而受阻时

此技能默认仅使用本地语音，不探测凭据：当 Voice 已注册时，计划和摘要使用 voice_tts；紧急提醒或备用方案使用快速的 say_tts。两者都不会占用云 API 配额，并会让语音内容保留在 Mac 上。只有在用户明确选择或已保存配置后，才会使用云端 TTS。如果该云服务提供商遇到配额、令牌、身份验证或配置错误，则本次会话会自动禁用云端 TTS，技能将改用本地语音；如果没有可用的本地工具，则仅使用文本。它绝不会自动尝试其他云服务提供商。临时更换服务提供商仅在本次会话中生效；只有用户要求记住该选择时才会更新配置。对于本地 say 的语音身份，除非用户主动选择了某个确切的已安装语音，否则请将 voice 留空，以使用主机的系统语音。

许可证

MIT