金大哥 - claude-code-tts MCP 详情

article

README

🚀 Claude Code TTS 插件

Claude Code TTS 插件是一个文本转语音（TTS）的 MCP 服务器插件，它借助 OpenAI 的 TTS API 将文本转换为语音。在使用 Claude 工作时，你可以获得语音反馈，极大地提升工作体验！

🚀 快速开始

快速安装

# 一键安装
curl -fsSL https://raw.githubusercontent.com/ybouhjira/claude-code-tts/main/install.sh | bash

或者手动安装：

git clone https://github.com/ybouhjira/claude-code-tts.git ~/.claude/plugins/claude-code-tts
cd ~/.claude/plugins/claude-code-tts
make install

配置

设置你的 OpenAI API 密钥：

export OPENAI_API_KEY="sk-..."

或者将其添加到你的 shell 配置文件（如 ~/.zshrc 或 ~/.bashrc）中。

运行要求

Go 1.21 及以上版本（用于从源代码构建）
拥有 TTS 访问权限的 OpenAI API 密钥
音频播放器：
- macOS：afplay（系统自带）
- Linux：mpv、ffplay 或 mpg123
- Windows：PowerShell（系统自带）

✨ 主要特性

确定性自动语音播放：Claude 的每个回复都会自动语音播放（通过停止钩子实现）
6 种高品质语音：alloy、echo、fable、onyx、nova、shimmer
工作池架构：非阻塞队列，支持并发处理
互斥锁保护的播放机制：一次只播放一个音频，避免重叠
跨平台支持：支持 macOS（afplay）、Linux（mpv/ffplay/mpg123）、Windows（PowerShell）
独立 CLI：speak-text 二进制文件，无需 MCP 即可直接进行文本转语音

📦 安装指南

一键安装

curl -fsSL https://raw.githubusercontent.com/ybouhjira/claude-code-tts/main/install.sh | bash

手动安装

git clone https://github.com/ybouhjira/claude-code-tts.git ~/.claude/plugins/claude-code-tts
cd ~/.claude/plugins/claude-code-tts
make install

💻 使用示例

speak(text, voice)

将文本转换为语音并播放。

参数： | 参数 | 类型 | 是否必需 | 描述 | |------|------|----------|------| | text | 字符串 | 是 | 要朗读的文本（最大 4096 个字符） | | voice | 字符串 | 否 | 要使用的语音（默认：alloy） |

可用语音： | 语音 | 描述 | |------|------| | alloy | 中性、平衡的语音 | | echo | 男性、温暖的语音 | | fable | 英式口音的语音 | | onyx | 低沉的男性语音 | | nova | 友好的女性语音 | | shimmer | 柔和的女性语音 |

示例：

使用 speak 工具以 nova 语音朗读 "Build completed successfully!"

tts_status()

获取 TTS 系统的当前状态。

返回值：

{
  "worker_count": 2,
  "queue_size": 50,
  "queue_pending": 0,
  "total_processed": 15,
  "total_failed": 0,
  "is_playing": false,
  "recent_jobs": [...]
}

自动 TTS（确定性）

此插件包含一个 停止钩子，它会自动朗读 Claude 每个回复的第一句话，无需额外配置，即装即用。

工作原理：

Claude 回复 → 停止钩子触发 → 提取第一句话 → 播放音频

该钩子在后台运行，不会阻塞 Claude 的回复。

speak-text CLI

一个独立的二进制文件，无需通过 MCP 即可直接进行文本转语音：

# 基本用法
speak-text "Hello world"

# 选择语音
speak-text -voice onyx "Error occurred"

安装后，该二进制文件位于 ~/.claude/plugins/claude-code-tts/bin/speak-text。

📚 详细文档

项目结构

claude-code-tts/
├── cmd/
│   ├── tts-server/
│   │   └── main.go           # MCP 服务器入口点
│   └── speak-text/
│       └── main.go           # 独立 CLI 二进制文件
├── hooks/
│   └── auto-speak.sh         # 确定性 TTS 的停止钩子
├── internal/
│   ├── audio/
│   │   └── player.go         # 跨平台音频播放
│   ├── server/
│   │   ├── server.go         # MCP 服务器和工具处理程序
│   │   └── worker.go         # 工作池实现
│   └── tts/
│       └── openai.go         # OpenAI TTS 客户端
├── plugin.json                # 插件元数据和钩子配置
├── Makefile                   # 构建自动化
└── install.sh                 # 一键安装脚本

从源代码构建

# 克隆仓库
git clone https://github.com/ybouhjira/claude-code-tts.git
cd claude-code-tts

# 构建
make build

# 安装到 Claude Code 插件目录
make install

# 运行测试
make test

🔧 技术细节

┌─────────────────────────────────────────────────────────────┐
│                     Claude Code                              │
│                         │                                    │
│                    MCP Protocol                              │
│                         │                                    │
│  ┌──────────────────────▼──────────────────────────────┐    │
│  │              TTS MCP Server (Go)                     │    │
│  │  ┌─────────────────────────────────────────────┐    │    │
│  │  │              Tool Handlers                   │    │    │
│  │  │   speak(text, voice)  │  tts_status()       │    │    │
│  │  └─────────────┬─────────┴─────────────────────┘    │    │
│  │                │                                     │    │
│  │  ┌─────────────▼─────────────────────────────┐      │    │
│  │  │           Worker Pool (2 workers)          │      │    │
│  │  │  ┌─────────┐    ┌─────────────────────┐   │      │    │
│  │  │  │ Job     │───►│ Queue (50 slots)    │   │      │    │
│  │  │  │ Submit  │    └──────────┬──────────┘   │      │    │
│  │  │  └─────────┘               │              │      │    │
│  │  │                   ┌────────▼────────┐     │      │    │
│  │  │                   │ Worker 1 │ 2    │     │      │    │
│  │  │                   └────────┬────────┘     │      │    │
│  │  └────────────────────────────│──────────────┘      │    │
│  │                               │                      │    │
│  │  ┌────────────────────────────▼──────────────────┐  │    │
│  │  │              OpenAI TTS API                    │  │    │
│  │  │         POST /v1/audio/speech                  │  │    │
│  │  │         Model: tts-1                           │  │    │
│  │  └───────────────────┬────────────────────────────┘  │    │
│  │                      │                               │    │
│  │  ┌───────────────────▼────────────────────────────┐  │    │
│  │  │         Audio Player (Mutex Protected)          │  │    │
│  │  │   macOS: afplay │ Linux: mpv │ Win: PowerShell  │  │    │
│  │  └─────────────────────────────────────────────────┘  │    │
│  └──────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE。

🔧 故障排除

"OPENAI_API_KEY 环境变量是必需的"

设置你的 OpenAI API 密钥：

export OPENAI_API_KEY="sk-..."

"在 Linux 上未找到合适的音频播放器"

安装以下播放器之一：mpv、ffplay 或 mpg123：

# Ubuntu/Debian
sudo apt install mpv

# Fedora
sudo dnf install mpv

# Arch
sudo pacman -S mpv

在 macOS 上音频无法播放

检查 afplay 是否正常工作：

# 使用示例音频文件进行测试
afplay /System/Library/Sounds/Ping.aiff

队列已满

默认队列大小为 50。如果达到此限制：

等待当前任务完成
检查 tts_status() 查看待处理任务
随着任务的处理，队列会逐渐清空

高延迟

OpenAI TTS API 每个请求通常需要 1 - 3 秒
音频文件必须完全下载后才能播放
考虑缩短消息长度以获得更快的反馈

API 费用

此插件使用 OpenAI 的 tts-1 模型：

费用：每 1000 个字符约 $0.015
示例："Hello, world!"（13 个字符）≈ $0.0002

贡献

欢迎贡献代码！请参阅 CONTRIBUTING.md 获取贡献指南。

claude-code-tts