AI导哈

语音交互服务

mcp-claude-say 是一个为 Claude Code 提供的语音交互服务，支持文本到语音（TTS）和语音到文本（STT）功能，实现完整的语音对话体验。

  • by alamparelli
  • Python
  • 本地部署
  • 7 星标
  • 更新于
在 GitHub 查看 alamparelli/mcp-claude-say

使用说明

mcp克劳德说

仅限macOS -使用本地macOS语音合成和Parakeet MLX进行STT

Claude Code的语音交互MCP服务器。包括文本到语音（TTS）和语音到文本（STT），以获得完整的语音对话体验。

特性

  • 语音应答 -克劳德大声说出了自己的回答
  • 语音输入 -使用按键通话（PTT）与克劳德通话
  • 全对话模式 -完整的语音循环 /conversation
  • 快速本地STT -使用长尾小鹦鹉MLX（针对苹果硅优化）
  • 多语言 -能说并理解多种语言
  • 轻量级 -默认情况下使用本地macOS语音合成，没有外部API

TTS后端选项

根据您的需求选择TTS后端：

后端 质量 存储 延迟 免费层
macOS （默认） 基本 0 即时 无限制
谷歌云 良好 0 ~0.5s 1M字符/月
话匣子 优秀 11GB ~0.3s 无限制

选项1:macOS（默认）

无需设置。使用本地 say 命令。语音是机器人的，但在任何地方都能工作。

选项2:Google Cloud TTS（推荐）

声音自然，存储空间为零。

定价层次：

级别 质量 价格
Neural2 良好 免费（1M字符/月）
工作室 更好 0.16/100万美元字符
旅程 对话 每百万字符30美元
Chirp3 HD 最佳（双子座） 0.30美元/百万个字符

设置：

  1. 在以下位置创建Google Cloud项目 console.cloud.google.com
  2. 启用 文本到速度API
  3. 在处创建API密钥 API和服务>凭据

通过安装程序配置（推荐）：

跑 ./install.sh 并在提示时选择“Google Cloud TTS”。安装程序将指导您输入API密钥并选择语音。

或手动配置：

编辑 ~/.mcp-claude-say/.env:

TTS_BACKEND=google
GOOGLE_CLOUD_API_KEY=your-api-key-here
GOOGLE_VOICE=en-US-Neural2-F
GOOGLE_LANGUAGE=en-US

然后重新启动Claude Code。

声音示例：

语音 层级 描述
en-US-Neural2-F 免费 美国女性（默认）
en-US-Journey-O 付费 美国女性，会话型
en-GB-Chirp3-HD-Erinome 付费 英国女性
en-GB-Chirp3-HD-Aoede 付费 英国女性
en-US-Neural2-D 免费 美国男性

看 所有的声音 更多选择。

选项3：聊天盒（局部神经TTS）

最高质量，100%本地运行，但需要11GB的存储空间来存储模型权重。

设置：

# Requires Python 3.11 (Chatterbox doesn't support 3.12+)
python3.11 -m venv ~/.mcp-claude-say/venv-tts
source ~/.mcp-claude-say/venv-tts/bin/activate
pip install chatterbox-tts uvicorn fastapi torchaudio

# Add a voice sample (5-10 seconds of clear speech, 24kHz WAV)
mkdir -p ~/.mcp-claude-say/voices
# Copy your sample to voices/female_voice.wav

配置：

export TTS_BACKEND="chatterbox"

用途：

Chatterbox服务必须手动启动：

# Start the service (~5-10 sec to load model)
~/.mcp-claude-say/start_tts_service.sh

# Verify it's running
curl http://127.0.0.1:8123/health

# Stop when done (frees ~1.5GB RAM)
~/.mcp-claude-say/stop_tts_service.sh
因素 影响
存储空间 模型重量约11GB
RAM 运行时约1.5GB
首次加载 5-10秒

如果服务未运行，TTS将回退到macOS say.

单线安装

git clone https://github.com/alamparelli/mcp-claude-say.git && cd mcp-claude-say && ./install.sh

或者，如果你已经克隆了仓库：

./install.sh

交互式安装程序将指导您完成以下操作：

  1. STT后端选择 -长尾小鹦鹉MLX或苹果语音分析仪
  2. TTS后端选择 -macOS说或谷歌云TTS
  3. 谷歌云设置 （如果选择）-API键和语音选择

安装程序的作用

  1. 创建Python虚拟环境
  2. 安装依赖项（MCP、长尾小鹦鹉MLX、音响设备、pynput）
  3. 创造 ~/.mcp-claude-say/.env 使用您的TTS配置
  4. 安装两项技能： /speak 和 /conversation
  5. 在Claude Code设置中配置两个MCP服务器

配置文件

安装后，您的TTS设置将存储在 ~/.mcp-claude-say/.env:

# TTS Backend: macos, google
TTS_BACKEND=macos

# Google Cloud TTS settings (only used if TTS_BACKEND=google)
GOOGLE_CLOUD_API_KEY=your-api-key
GOOGLE_VOICE=en-US-Neural2-F
GOOGLE_LANGUAGE=en-US

编辑此文件并重新启动Claude Code以更改设置。看 env.template 对于所有选项。

CLI选项

对于脚本/自动安装：

# Install with macOS TTS (default)
./install.sh --parakeet --tts-macos

# Install with Google Cloud TTS
./install.sh --parakeet --tts-google --google-api-key "YOUR_API_KEY"

# TTS only mode (no STT)
./install.sh --tts-only --tts-google

用法

安装后，重新启动Claude Code。

语音模式（仅TTS）

/speak

克劳德会大声说出自己的回答。

对话模式（TTS+STT）

/conversation

全语音循环，自动转弯：

  1. 按 正确的命令 开始录制
  2. 说出你的信息
  3. 发言结束后，录音会自动停止（VAD）
  4. 克劳德转录并口头回应
  5. Claude完成后，录制会自动重新开始
  6. 自然地继续对话！

驳船驶入： 按 正确的命令 随时打断克劳德的话。

说 “会议结束” 结束谈话。

按键通话键

密钥 描述
cmd_r 右命令（默认，推荐）
cmd_l+s 左命令+S
cmd_r+m 右命令+M
alt_l, alt_r 选项键
f13, f14, f15 功能键

MacBook热键笔记

有些热键在MacBook上工作不好：

热键 问题
alt_l+c ❌ 生产 ç macOS上的字符
f13, f14, f15 ❌ MacBook没有这些钥匙
ctrl_r ❌ MacBook没有正确的控制权
cmd_l+s ⚠️ 在大多数应用程序中与“保存”冲突
cmd_r ✅ 仅凭正确的指挥-没有冲突，无处不在

建议： 使用 cmd_r （右命令）用于MacBook上的PTT。

需求

  • macOS （使用本地 say 命令+长尾小鹦鹉MLX）
  • 苹果芯片 建议用于快速STT
  • Python 3.9+
  • 克劳德代码 命令行界面

MCP服务器

安装程序配置了两个MCP服务器：

克劳德说（TTS）

工具 说明
speak(text, voice?, speed?) 排队发言
speak_and_wait(text, voice?, speed?) 说话并等待完成
stop_speaking() 停车并清空队列

克劳德倾听（STT）

工具 说明
start_ptt_mode(key?) 启动按键通话模式
stop_ptt_mode() 停止PTT模式
get_ptt_status() 获取当前状态
get_segment_transcription() 获取转录文本

文件结构

~/.mcp-claude-say/
├── .env                   # TTS configuration (TTS_BACKEND, GOOGLE_CLOUD_API_KEY, etc.)
├── mcp_server.py          # TTS server
├── listen/                # STT module
│   ├── mcp_server.py      # STT server
│   ├── parakeet_transcriber.py
│   └── ptt_controller.py
├── shared/                # Coordination
└── venv/                  # Python environment

~/.claude/skills/
├── speak/                 # /speak skill
│   └── SKILL.md
└── conversation/          # /conversation skill
    └── SKILL.md

卸载

./uninstall.sh

卸载程序会询问您是否要删除缓存的模型（长尾鹦鹉MLX~2.3GB）。选择“保留型号”以便以后更快地重新安装，或选择“删除所有内容”以释放磁盘空间。

故障排除

没有声音

# Test macOS speech
say "Hello world"

STT不工作

# Check Parakeet MLX
~/.mcp-claude-say/venv/bin/python -c "import parakeet_mlx; print('OK')"

# Check audio capture
~/.mcp-claude-say/venv/bin/python -c "import sounddevice; print(sounddevice.query_devices())"

未检测到PTT键（特别是在VSCode中）

PTT热键使用 pynput 这需要 可访问权限 在macOS上。如果没有这些权限，键盘侦听器将成功启动，但永远不会收到按键事件。

要修复：

  1. 打开 系统设置 → 隐私和安全 → 无障碍
  2. 点击 + 按钮（需要时使用密码解锁）
  3. 添加您的终端应用程序：
    • 对于VSCode： /Applications/Visual Studio Code.app
    • 对于光标： /Applications/Cursor.app
    • 对于终端： /Applications/Utilities/Terminal.app
    • 对于iTerm2： /Applications/iTerm.app
  4. 启用复选框 应用程序旁边
  5. 完全重新启动应用程序 （退出并重新打开）

仍然不工作吗？

  • 尝试其他热键： start_ptt_mode("f13") 或 start_ptt_mode("alt_r")
  • 检查日志： tail -f /tmp/claude-listen.log
  • 验证pynput是否正常工作：在Claude Code之外运行一个简单的pynput测试脚本

注： 某些键可能在没有辅助功能权限的情况下工作（如功能键F13-F15），但修饰键（Cmd、Alt、Ctrl）始终需要权限。

演出

度量 值
STT速度 ~60倍实时（长尾小鹦鹉MLX）
STT RAM ~2gb
TTS延迟 <100ms

注： 当长尾小鹦鹉MLX模型加载到记忆中时，第一次转录很慢（约10-15秒）。随后的转录几乎是即时的。

测试环境

环境 状态 注释
终端 （macOS原生） ✅ 作品
iTerm2 ✅ 作品
光标 ⚠️ 应该有效 尚未测试
VSCode终端 +克劳德代码CLI ✅ 作品
VSCode +克劳德代码GUI扩展 ❌ 不工作 对话模式不稳定

需要帮助！ 如果你在其他环境中测试mcp-claude，请 打开一个问题 报告你的结果。

更新日志

v0.3.0-语音对话模式（2026年1月）

Kokoro TTS后端 （第9页）

  • 新 kokoro TTS后端使用MLX Audio，支持9种语言的54种语音
  • 支持英语、西班牙语、法语、意大利语、葡萄牙语、日语、中文、印地语
  • 配置为 TTS_BACKEND=kokoro 和 KOKORO_VOICE=af_heart

无缝对话流程

  • VAD自动停止：发言结束后录音会自动停止
  • 自动启动：Claude响应后，录制会自动重新开始
  • 语音打断：按PTT打断克劳德的话
  • 按一下PTT开始，对话自然流畅

v0.2.0-TTS配置（2026年1月）

安装程序改进 （公关#7）

  • 交互式TTS后端选择（macOS、Google Cloud、Kokoro）
  • 带有API键和语音选择的Google Cloud TTS设置向导
  • 通过以下方式进行集中配置 ~/.mcp-claude-say/.env
  • 卸载期间的模型缓存清理选项

许可证

麻省理工学院

享受你的语音助手吧！

相关 MCP