Yakrover Talk MCP

谈mcp

ElevenLabs提供的语音输出MCP服务器。将LLM响应转换为自然的语音关键点，通过PipeWire播放到任何音频接收器，包括通过AirPlay播放的HomePod。

建筑

┌─────────────────────┐         ┌──────────────────────────────────────┐
│   Client Machine    │         │   Server Machine (with speakers)     │
│                     │         │                                      │
│  ┌───────────────┐  │  MCP    │  ┌───────────┐    ┌──────────────┐  │
│  │  Claude Code  │──┼────────►│  │ server.py │───►│   tts.py     │  │
│  └───────────────┘  │ stdio   │  │ (FastMCP) │    └──────┬───────┘  │
│         │           │  or     │  └─────┬─────┘           │          │
│  ┌──────▼────────┐  │ http    │        │           ┌─────▼────────┐ │
│  │  .mcp.json    │  │         │        │           │ ElevenLabs   │ │
│  └───────────────┘  │         │        ▼           │ API          │ │
│                     │         │  ┌───────────┐     └──────────────┘ │
│  Transport:         │         │  │ audio.py  │◄── templates.json   │
│   • stdio (local)   │         │  └─────┬─────┘                     │
│   • http  (remote)  │         │        │                            │
│                     │         │  ┌─────▼─────┐   ┌──────────────┐  │
│                     │         │  │  pw-play   │──►│  PipeWire    │  │
│                     │         │  └───────────┘   └──────┬───────┘  │
│                     │         │                         │          │
│                     │         │                  ┌──────▼───────┐  │
│                     │         │                  │   HomePod    │  │
│                     │         │                  │ (AirPlay)    │  │
│                     │         │                  └──────────────┘  │
└─────────────────────┘         └──────────────────────────────────────┘

在Excalidraw上查看交互式图表

运作原理

1. Claude Code调用MCP工具(speak, play_template等）通过stdio或HTTP
2. server.py 将请求路由到ElevenLabs TTS或预先录制的模板
3. audio.py 通过PipeWire播放音频 pw-play
4. PipeWire将音频路由到配置的接收器（通过AirPlay/RAOP或本地扬声器的HomePod）

先决条件

• Python 3.11+
• 紫外线 （Python包管理器）
• PipeWire （音频系统——大多数现代Linux上的默认设置）
• 十一实验室 API密钥
• 克劳德代码 （CLI）

设置

1.克隆并安装

git clone git@github.com:YakRoboticsGarage/yakrover-talk-mcp.git
cd yakrover-talk-mcp
uv venv && uv pip install -e .

2.获取ElevenLabs API密钥

1. 注册地址： 十一个实验室.io
2. 首选 配置文件+API密钥 （左下）→ 复制API密钥

3.创建您的 .env 文件

服务器加载 .env 自动通过 python-dotenv --没必要 source 它

# Required
ELEVENLABS_API_KEY=your_key_here

# Transport (uncomment for remote server mode)
# MCP_TRANSPORT=http
# MCP_HOST=0.0.0.0
# MCP_PORT=8000

# Audio (optional)
# AUDIO_PLAYER=pw-play
# PIPEWIRE_SINK=your_sink_name
# AUDIO_FILES_DIR=/path/to/sample-audio

4.设置音频模板（可选）

cp sample-audio/template-example.json sample-audio/templates.json

编辑 templates.json 并添加您的 .mp3 文件到 sample-audio/。参见 模板格式 在......下面

5.将HomePod设置为音频接收器（可选）

如果你想通过HomePod播放音频：

bash scripts/setup-homepod.sh

这将配置PipeWire RAOP发现、防火墙规则和打印可用接收器。然后管理您的音频接收器：

bash scripts/audio-sink.sh list        # List available sinks
bash scripts/audio-sink.sh connect     # Set a sink as default
bash scripts/audio-sink.sh status      # Show current default
bash scripts/audio-sink.sh disconnect  # Switch to local speakers

运行服务器

选项A：本地（stdio）——与Claude Code相同的机器

创建 .mcp.json 在项目根目录中（或从以下位置复制 mcp-example.json):

{
  "mcpServers": {
    "talk-mcp": {
      "command": "uv",
      "args": ["run", "python", "server.py"],
      "cwd": "/path/to/talk-mcp",
      "env": {
        "ELEVENLABS_API_KEY": "your_key_here",
        "AUDIO_PLAYER": "pw-play"
      }
    }
  }
}

当您在此目录中打开会话时，Claude Code将自动启动服务器。

选项B：远程（HTTP）--不同计算机上的服务器

当Claude Code在您的笔记本电脑上运行，但音频应在带有扬声器或HomePod的台式机/服务器上播放时，请使用此功能。

步骤1：查找服务器的本地IP

在服务器计算机（带扬声器的计算机）上：

# Linux
hostname -I | awk '{print $1}'

# macOS
ipconfig getifaddr en0

输出示例： 192.168.1.42

步骤2：配置 .env 用于远程模式

在服务器计算机上，编辑 .env 要启用HTTP传输：

ELEVENLABS_API_KEY=your_key_here
MCP_TRANSPORT=http
MCP_HOST=0.0.0.0
MCP_PORT=8000

步骤3：启动服务器

cd /path/to/talk-mcp
uv run python server.py

您应该看到服务器启动并继续监听 http://0.0.0.0:8000/mcp （流式HTTP，MCP规范2025-06-18）。

步骤4：验证服务器是否可访问

从您的客户端计算机（笔记本电脑）确认您可以访问它：

curl http://192.168.1.42:8000/mcp

您应该得到一个响应（不是连接被拒绝错误）。

步骤5：在客户端配置Claude代码

在客户端计算机上，创建 .mcp.json 在项目根目录中：

{
  "mcpServers": {
    "talk-mcp": {
      "url": "http://192.168.1.42:8000/mcp"
    }
  }
}

替换 192.168.1.42 使用服务器的实际IP。

步骤6：打开克劳德代码

在以下目录中启动新的Claude Code会话 .mcp.json。它将自动连接到远程通话mcp服务器。任何 speak() 或 play_template() 呼叫将在服务器机器上播放音频。

注： 默认情况下，HTTP服务器没有身份验证——只在受信任的本地网络上运行它，或者将其放在具有身份验证的反向代理后面。 提示： 如果连接被拒绝，请检查没有防火墙阻止服务器上的端口8000： sudo ufw allow 8000/tcp

MCP工具

语言路由

这些工具通过其文档字符串强制执行语言感知路由：

音频回复模板

模板是预先录制的音频片段，在特定情境下播放，而不是TTS。

模板格式(sample-audio/templates.json)

{
  "greeting": {
    "file": "greeting.mp3",
    "description": "A friendly greeting. Use when the user says hello."
  },
  "victory": {
    "file": "victory.mp3",
    "description": "A celebration sound. Use when a task completes successfully."
  }
}

这 description 是LLM读取的内容，用于决定何时播放每个模板——将其作为明确的指令编写。

Git跟踪

项目结构

talk-mcp/
├── server.py                  # FastMCP server, tool definitions
├── config.py                  # Environment variables and defaults
├── prompts.py                 # Spoken keypoints system prompt
├── tts.py                     # ElevenLabs synthesis helper
├── audio.py                   # Audio playback via pw-play
├── pyproject.toml             # Dependencies and entry point
├── mcp-example.json           # Example MCP config (local + remote)
├── sample-audio/
│   ├── template-example.json  # Example template format
│   ├── templates.json         # Your templates (gitignored)
│   └── *.mp3                  # Audio files (gitignored)
├── scripts/
│   ├── setup-homepod.sh       # One-time HomePod/PipeWire setup
│   └── audio-sink.sh          # Audio sink management
└── docs/
    └── plan.md                # Design spec

环境变量

许可证

Apache 2.0——请参阅 许可证.