Speakup MCP

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）
• 添加 speakup CLI到您的PATH(~/.local/bin)
• 启动后台服务

或手动安装：

git clone https://github.com/zachswift615/speakup-mcp.git
cd speakup-mcp
./install.sh

项目设置

在任何项目目录中，运行：

speakup init my-project-name

这将：

1. 创建/更新 .mcp.json 使用TTS服务器配置
2. 创建/更新 .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"
      }
    }
  }
}

环境变量

宣布模式：

• 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 messages

Web用户界面

打开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()

声调

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）
• 音频输出设备

许可证

麻省理工学院