内容
# 语音接口 Speech MCP Echo
> **基于**: [Kvadratni/speech-mcp](https://github.com/Kvadratni/speech-mcp) - 原始 Speech MCP 项目
用于多个 AI 命令行接口的语音接口 - Claude Code, Gemini CLI, Codex CLI, 以及兼容 MCP 的工具。
## 功能特点
- **多命令行支持**: 支持 Claude Code, Gemini CLI, Codex CLI, 以及任何兼容 MCP 的工具
- **持续聆听** *(新版 v0.2.0)*: 非阻塞后台聆听，自动重试静音
- **可配置 STT**: 本地 (faster-whisper) 或云端 (Groq Whisper, OpenAI Whisper, Google Speech)
- **可配置 TTS**: 本地 (pyttsx3) 或云端 (Google Cloud TTS, OpenAI TTS)
- **双语支持**: 英语和中文（繁体/简体）文本处理
- **JARVIS 摘要**: 将长篇响应压缩为简洁、有趣的摘要
## 快速开始
### 安装
```bash
# 从 git（推荐）
pip install 'speech-mcp-echo[recommended] @ git+https://github.com/lukechi1219/speech-mcp-echo.git@v0.2.1'
# 或从 wheel
pip install 'speech-mcp-echo[recommended] @ https://github.com/lukechi1219/speech-mcp-echo/releases/download/v0.2.1/speech_mcp_echo-0.2.1-py3-none-any.whl'
```
### 命令行接口集成
#### Claude Code（主要目标）
添加到 `~/.claude.json`:
```json
{
"mcpServers": {
"speech-mcp-echo": {
"command": "speech-mcp-echo"
}
}
}
```
**可选**: 在 `~/.claude/settings.json` 中自动批准语音工具，以避免确认提示：
```json
{
"permissions": {
"allow": [
"mcp__speech-mcp-echo__start_conversation",
"mcp__speech-mcp-echo__voice_listen",
"mcp__speech-mcp-echo__voice_speak",
"mcp__speech-mcp-echo__voice_reply",
"mcp__speech-mcp-echo__voice_config",
"mcp__speech-mcp-echo__voice_status",
"mcp__speech-mcp-echo__start_listening",
"mcp__speech-mcp-echo__check_listening",
"mcp__speech-mcp-echo__cancel_listening"
]
}
}
```
然后重启 Claude Code 并说： **"让我们进行语音对话"**
#### 其他命令行接口
**Goose CLI**:
```bash
goose session --with-extension "speech-mcp-echo"
```
**Gemini CLI**: 添加到 `~/.gemini/settings.json`（格式与 Claude Code 相同）
**Codex CLI**: 添加到 `~/.codex/config.toml`:
```toml
[mcp_servers.speech-mcp-echo]
command = "speech-mcp-echo"
```
## 为什么选择这些技术？
### STT: Groq Whisper（推荐）
我们选择 **Groq Whisper API** 作为推荐的 STT 引擎，因为：
- **最准确**: 使用 whisper-large-v3-turbo 模型（~12% WER vs ~23% for 本地基础模型）
- **极快**: 在 Groq 的 LPU 硬件上达到 216 倍实时速度
- **无需本地资源**: 无需模型下载，无需 GPU/CPU 负载
- **慷慨的免费层**: 具有慷慨的速率限制的免费 API
- **易于设置**: 只需设置 `GROQ_API_KEY` 环境变量
- **OpenAI 兼容**: 使用相同的 `openai` SDK，具有不同的基准 URL
```bash
# 设置您的 Groq API 密钥（在 https://console.groq.com 上免费获取）
export GROQ_API_KEY="gsk_..."
```
### STT: faster-whisper（本地替代方案）
**faster-whisper** 是完全离线操作的良好替代方案：
- **轻量级**: ~150MB vs ~1.5GB for OpenAI 的原始 whisper
- **快速**: 使用 CTranslate2 优化比原始 whisper 快 4 倍
- **离线**: 完全离线工作，无需 API 成本
- **CPU 友好**: 在 CPU 上运行良好，具有 int8 量化
### TTS: Google Cloud TTS（推荐）
我们选择 **Google Cloud TTS** 作为主要的 TTS 引擎，因为：
- **无重依赖**: 不像 Kokoro 需要 PyTorch（~2GB），Google Cloud TTS 使用简单的 REST API
- **高质量**: 具有自然语调的神经语音
- **多语言**: 优秀的英语、中文（繁体/简体）和 40 多种语言支持
- **灵活认证**: 多种认证方法（见下文）
- **成本效益**: 免费层包括 400 万字符/月
- **跨平台**: 在 macOS、Linux 和 Windows 上运行
#### Google Cloud TTS 认证选项
选择最适合您设置的认证方法：
**选项 A: gcloud CLI（推荐开发者）**
```bash
# 安装 gcloud CLI
brew install google-cloud-sdk # macOS
# 或：https://cloud.google.com/sdk/docs/install
# 登录和配置
gcloud auth login
gcloud config set project YOUR_PROJECT_ID
```
**选项 B: 服务账户（推荐服务器/生产环境）**
```bash
# 1. 在 Google Cloud Console 中创建服务账户
# - 进入 IAM & Admin > 服务账户
# - 创建具有 "Cloud Text-to-Speech API User" 角色的账户
# - 下载 JSON 密钥文件
# 2. 设置环境变量
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"
# 3. 可选设置项目 ID（如果密钥文件中没有）
export GOOGLE_CLOUD_PROJECT="your-project-id"
```
**选项 C: Python 客户端库**
```bash
# 安装库
pip install google-cloud-texttospeech
# 然后使用选项 A 或 B 进行身份验证
# 库将自动检测凭据
```
适配器会自动尝试这些方法，并使用第一个有效的方法。
#### 为什么不使用 Kokoro？
Kokoro 是一个优秀的本地 TTS 引擎，但它需要：
- PyTorch（~2GB 下载）
- CUDA 以获得最佳性能
- 额外的语言模型（misaki）
对于大多数用户，Google Cloud TTS 提供更好的质量和更简单的设置。Kokoro 仍然作为可选的本地替代方案，供喜欢完全离线操作的用戶使用。
## 配置
配置存储在 `~/.config/speech-mcp-echo/config.json`：
```json
{
"stt": {
"engine": "groq",
"model": "whisper-large-v3-turbo",
"language": "auto",
"timeout": 45,
"silence_retry_count": 10,
"retry_prompt_type": "beep"
},
"tts": {
"engine": "google",
"voice": "cmn-TW-Standard-B",
"language": "cmn-TW"
},
"summarizer": {
"enabled": true,
"personality": "jarvis",
"language": "en"
}
}
```
### 持续聆听设置
| 设置 | 默认值 | 描述 |
|---------|---------|-------------|
| `stt.timeout` | 45 | 每次尝试的语音等待时间（秒） |
| `stt.silence_retry_count` | 10 | 检测到静音时的重试次数（~7.5 分钟容忍度） |
| `stt.retry_prompt_type` | "beep" | 重试提示： "beep", "voice", 或 "silent" |
```
### 支持的语言
| 语言 | STT (Groq/faster-whisper) | TTS (Google Cloud) |
|----------|---------------------------|-------------------|
| 英语 | ✅ | ✅ en-US, en-GB |
| 中文（繁体） | ✅ | ✅ cmn-TW |
| 中文（简体） | ✅ | ✅ cmn-CN |
| 日语 | ✅ | ✅ ja-JP |
### 环境变量
API 密钥从环境变量中读取：
- `GROQ_API_KEY` - 用于 Groq Whisper STT（推荐）
- `OPENAI_API_KEY` - 用于 OpenAI Whisper STT 和 TTS
- `GOOGLE_APPLICATION_CREDENTIALS` - 用于 Google Cloud 服务（如果使用 gcloud CLI，则可选）
- `ANTHROPIC_API_KEY` - 用于基于 Claude 的摘要
## 架构
```
src/speech_mcp_echo/
├── __init__.py # 主要入口点
├── __main__.py # 模块执行
├── audio_processor.py # 音频捕获、播放、提示
├── constants.py # 集中常量
├── server.py # 统一 MCP 服务器（所有工具）
├── config/ # 配置管理
├── core/
│ └── voice_engine.py # STT、TTS、摘要
├── resources/
│ └── audio/ # 音频提示文件 (.wav)
├── stt_adapters/ # 语音转文本引擎
│ ├── groq_whisper_adapter.py # 云端（推荐）
│ ├── faster_whisper_adapter.py # 本地
│ ├── openai_whisper_adapter.py # 云端
│ └── google_speech_adapter.py # 云端
├── tts_adapters/ # 文本转语音引擎
│ ├── google_tts_adapter.py # 云端（推荐）
│ └── openai_tts_adapter.py # 云端
├── summarizer/ # 响应摘要
│ ├── local_summarizer.py # 基于规则的 JARVIS 个性化
│ └── llm_summarizer.py # 基于 LLM（占位符）
└── utils/
└── logger.py # 集中日志记录
```
## 开发
```bash
# 克隆并在开发模式下安装
git clone https://github.com/lukechi1219/speech-mcp-echo.git
cd speech-mcp-echo
pip install -e ".[dev]"
# 运行测试
pytest tests/
```
## 许可证
MIT
## 鸣谢
改编自 [Kvadratni/speech-mcp](https://github.com/Kvadratni/speech-mcp) ，具有多命令行支持。
