SpeakUp MCP服务器
一个MCP服务器，提供Claude Code文本到语音功能，支持多个并发实例、消息队列和用于监控的web UI。
特性
- 集中式队列 -多个Claude Code实例共享一个音频输出，没有重叠
- 项目鉴定 -每条消息都会宣布它来自哪个项目
- Web用户界面 -监视队列、历史记录，并在以下位置停止播放http://localhost:7849
- CLI控制 -
speakup status,speakup stop,speakup history - 5种情绪音调 -中立、兴奋、关心、冷静、紧急
- 流媒体播放 -音频立即开始，不等待完全合成
- 持久的历史 -所有消息的SQLite存储
建筑
Claude Code #1 Claude Code #2 Claude Code #3
│ │ │
▼ ▼ ▼
MCP Server #1 MCP Server #2 MCP Server #3
(thin client) (thin client) (thin client)
│ │ │
└─────────────────────┼─────────────────────┘
▼
┌────────────────────────┐
│ SpeakUp Service │
│ localhost:7849 │
│ ───────────────── │
│ • FIFO queue │
│ • SQLite history │
│ • Web UI │
│ • Streaming playback │
└────────────────────────┘快速设置
单线安装：
curl -fsSL https://raw.githubusercontent.com/zachswift615/speakup-mcp/main/install.sh | bash这将：
- 将仓库克隆到
~/.speakup/src - 创建虚拟环境
- 安装所有依赖项
- 下载语音文件（约70MB）
- 添加
speakupCLI到您的PATH(~/.local/bin) - 启动后台服务
或手动安装：
git clone https://github.com/zachswift615/speakup-mcp.git
cd speakup-mcp
./install.sh项目设置
在任何项目目录中，运行：
speakup init my-project-name这将：
- 创建/更新
.mcp.json使用TTS服务器配置 - 创建/更新
.claude/CLAUDE.md附带Claude的使用说明
然后重新启动Claude Code以加载新配置。
选项
# Use full announcements ("This is Claude from my-project: ...")
speakup init my-project --announce full
# Disable announcements
speakup init my-project --announce none手动配置
如果您更喜欢手动设置，请添加到项目的 .mcp.json:
{
"mcpServers": {
"tts": {
"command": "python",
"args": ["-m", "claude_tts_mcp.server"],
"env": {
"SPEAKUP_PROJECT": "my-project-name",
"SPEAKUP_ANNOUNCE": "prefix"
}
}
}
}环境变量
| 变量 | 值 | 描述 |
|---|---|---|
SPEAKUP_PROJECT | 任意字符串 | 消息中显示的项目名称（默认值：“claude”） |
SPEAKUP_ANNOUNCE | prefix, full, none | 如何宣布项目 |
宣布模式：
prefix-“我的项目：Hello world”（默认）full-“这是我的项目《Hello world》中的克劳德”none-“Hello world”（无公告）
CLI命令
# Project setup
speakup init
# Initialize SpeakUp in current directory
speakup init
--announce full # With full announcements
# Service management
speakup service start # Start the background service
speakup service stop # Stop the service
speakup service status # Check if service is running
# Playback control
speakup stop # Stop current playback and clear queue
speakup status # Show what's playing and queued
speakup history # Show recent messages
speakup history -n 50 # Show last 50 messagesWeb用户界面
打开http://localhost:7849查看：
- 正在播放 -正在讲话的当前消息
- 队列 -等待播放的消息
- 历史 -最近的消息状态（播放/跳过）
- 全部停止 按钮-停止播放并清除队列
当调用第一个MCP工具时，服务会自动启动。
用法
配置后，Claude Code可以使用TTS工具：
# Simple speech
speak(text="Hello world!")
# With emotional tone
speak(text="All tests passed!", tone="excited")
# Warning
speak(text="Found 3 errors", tone="concerned")
# Fast speech
speak(text="Quick update", speed=1.5)
# Stop current speech and clear queue
stop()声调
| 音色 | 效果 |
|---|---|
neutral | 默认，语音清晰 |
excited | 变化更多，速度稍快 |
concerned | 更平稳，更慢 |
calm | 非常平稳、轻松的步伐 |
urgent | 精力充沛，速度快 |
CLAUDE.md集成
将此添加到您的项目 CLAUDE.md 鼓励克劳德有效地使用TTS：
## Voice/TTS (Text-to-Speech)
Use `mcp__tts__speak_tool` to speak to the user aloud. Use it liberally - for thinking
out loud, narrating what you're doing, conversing naturally, or any time voice adds to
the experience.
**Parameters:**
- `text` (required): What to say
- `tone`: neutral | excited | concerned | calm | urgent (default: neutral)
- `speed`: 0.5 to 2.0 (default: 1.0)
- `interrupt`: Stop current speech before starting (default: true)
**Example uses:**
- Thinking through a problem out loud
- Announcing task completion or updates
- Reading errors or warnings aloud
- Conversational back-and-forth
**Tone guide:**
- `calm` - explanations, walkthroughs
- `urgent` - errors, critical issues
- `excited` - successes, good news
- `concerned` - warnings, risky operations
Use `mcp__tts__stop_tool` to stop speech mid-playback.为什么使用这个？
多实例支持
运行多个克劳德代码窗口？消息排队而不是互相交谈。每条消息都以其项目名称作为前缀，以便您知道哪个实例在说话。
子代理可见性
使用子代理驱动开发时，您通常对代理正在做什么的可见性有限。通过CLAUDE.md中的TTS指令，子代理在工作时宣布他们的进度，从而在不观看终端的情况下为您提供实时音频反馈。
代币高效
MCP接口最小：
- 回复:
{"success": true, "message_id": 1, "queue_position": 0}
没有冗长的有效载荷，没有不必要的元数据。
流媒体播放
音频在合成后立即开始播放，而不是等待完整生成。这大大缩短了较长文本首次发声的时间。
数据存储
- 历史数据库:
~/.speakup/history.db（SQLite） - 服务PID文件:
~/.speakup/service.pid - 语音模型:
~/.claude-tts/voices/
手动语音设置
如果您更喜欢手动设置，请下载默认语音：
mkdir -p ~/.claude-tts/voices/en_US-lessac-medium
cd ~/.claude-tts/voices/en_US-lessac-medium
curl -LO https://github.com/k2-fsa/sherpa-onnx/releases/download/tts-models/vits-piper-en_US-lessac-medium.tar.bz2
tar -xjf vits-piper-en_US-lessac-medium.tar.bz2 --strip-components=1
rm vits-piper-en_US-lessac-medium.tar.bz2发展
# Install dev dependencies
pip install -e ".[dev]"
# Run tests
pytest tests/ -v项目结构
src/claude_tts_mcp/
├── server.py # MCP server (thin client)
├── service.py # Background service with HTTP API + Web UI
├── cli.py # CLI commands (speakup)
├── queue_manager.py # Message queue and playback coordination
├── history.py # SQLite history storage
├── streaming_player.py # Streaming audio playback
├── sherpa_engine.py # sherpa-onnx TTS wrapper
├── tone_mapper.py # Tone → synthesis parameters
└── voice_manager.py # Voice model management需求
- Python 3.10+
- macOS（计划支持Linux/Windows）
- 音频输出设备
许可证
麻省理工学院