Pipecat MCP Server

Pipecat MCP Server 为你的 AI 助手（Claude Code / Codex CLI）赋予语音交互能力，基于 Pipecat 实现。它兼容所有 MCP 客户端。

核心概念：MCP Server 暴露语音和屏幕捕获工具给 AI 客户端，但它本身不提供麦克风和扬声器。音频输入输出由独立的传输层处理，默认使用 WebRTC，你可以通过浏览器连接到本地服务。

AI 客户端（Claude Code、Codex）负责控制对话，不是音频设备。要听到、说出或看到，你需要通过音频传输层连接。

架构流程

你(浏览器) ──WebRTC──▶ Pipecat Agent (STT/TTS) ◀──MCP──▶ Claude Code / Codex CLI
   ▲                        ▲                                ▲
   │                        │                                │
   音频                  语音工具                       AI 大脑
 (听/说)           (listen/speak/start/stop)          (理解/决策)

Related MCP server: voice-mcp-server

环境要求

• Python 3.10+

• uv 包管理器

• MiMo API Key（STT + TTS 云端服务，中文识别效果好于本地 Whisper）

安装

方式一：从 PyPI 安装

uv tool install pipecat-ai-mcp-server

方式二：克隆仓库本地安装

git clone https://github.com/xx5921/pipecat-mcp-server.git
cd pipecat-mcp-server
uv tool install -e .

配置环境变量

在项目目录创建 .env 文件：

# MiMo API Key（必填，用于语音识别和合成）
MIMO_API_KEY=你的MiMo_API_Key

# WebRTC Runner 配置（可选，以下为默认值）
PIPECAT_RUNNER_HOST=localhost
PIPECAT_RUNNER_PORT=7860
PIPECAT_RUNNER_TRANSPORT=webrtc

启动服务

pipecat-mcp-server

服务启动后：

• MCP Server 运行在 http://localhost:9090/mcp

• Pipecat Runner（WebRTC）运行在 http://localhost:7860

连接 Claude Code

步骤 1：添加 MCP Server

claude mcp add pipecat --transport http http://localhost:9090/mcp --scope user

Scope 选项：

• local：仅当前项目生效

• user：所有项目生效

• project：存储在项目的 .mcp.json 中

步骤 2：配置权限自动批准

创建 .claude/settings.local.json：

{
  "permissions": {
    "allow": [
      "mcp__pipecat__start",
      "mcp__pipecat__listen",
      "mcp__pipecat__speak",
      "mcp__pipecat__stop",
      "mcp__pipecat__list_windows",
      "mcp__pipecat__screen_capture",
      "mcp__pipecat__capture_screenshot"
    ]
  }
}

步骤 3：启动语音对话

1. 确保 pipecat-mcp-server 已启动

2. 在浏览器打开 http://localhost:7860，点击连接（这是你的麦克风和扬声器）

3. 在 Claude Code 中说："开始语音对话" 或直接说你想做的事

Claude 会自动调用以下流程：

1. start() → 启动 Pipecat 语音代理

2. listen() → 等待你说话，返回转录文字

3. Claude 思考并生成回复

4. speak(text) → TTS 播报回复

5. 循环 listen/speak 直到你说结束

6. stop() → 关闭语音通道

连接 Codex CLI

步骤 1：添加 MCP Server

codex mcp add pipecat --url http://localhost:9090/mcp

步骤 2：配置信任级别

在 Codex 中进入你的项目目录，Codex 会询问是否信任该目录。选择 Yes，这会在 ~/.codex/config.toml 中添加：

[projects."/path/to/your/project"]
trust_level = "trusted"

步骤 3：启动语音对话

1. 确保 pipecat-mcp-server 已启动

2. 在浏览器打开 http://localhost:7860，点击连接

3. 在 Codex 中输入 /talk 或说 "开始语音对话"

屏幕捕获与分析

你可以把屏幕（或某个窗口）共享给 AI 助手，让它帮你分析看到的内容。

可用工具：

• list_windows() — 列出所有可捕获的窗口

• screen_capture(window_id) — 开始捕获指定窗口（不传则捕获全屏）

• capture_screenshot() — 截取当前画面并保存为图片

使用示例：

• "列出我打开的窗口" → 返回窗口列表

• "捕获我的浏览器窗口" → 开始流式传输该窗口

• "这个报错是什么原因？" → AI 分析你的屏幕画面

• "这个 UI 设计怎么样？" → AI 给你反馈

支持平台：

• macOS — ScreenCaptureKit，支持窗口级捕获

• Linux (X11) — Xlib 窗口和全屏捕获

• Windows — 全屏捕获

自定义服务

切换 STT / TTS

在 .env 中通过环境变量切换语音识别和语音合成服务：

# STT provider: mimo / whisper
PIPECAT_STT_PROVIDER=whisper
# Whisper model: tiny / base / small / medium / large-v3
PIPECAT_STT_MODEL=medium
PIPECAT_STT_NO_SPEECH_PROB=0.4

# TTS provider: mimo / kokoro / piper / voxcpm
PIPECAT_TTS_PROVIDER=piper
# MiMo example: mimo_default / 冰糖 / 茉莉 / 苏打 / 白桦 / Mia / Chloe / Milo / Dean
# Kokoro example: af_heart
# Piper example: zh_CN-huayan-medium
PIPECAT_TTS_VOICE=zh_CN-huayan-medium
# Kokoro af_heart uses en; MiMo/Piper Chinese voices usually use zh.
PIPECAT_TTS_LANGUAGE=zh
# VoxCPM server URL (only for voxcpm provider)
PIPECAT_VOXCPM_URL=http://localhost:8000
# VoxCPM model name (optional, defaults to openbmb/VoxCPM2)
PIPECAT_VOXCPM_TTS_MODEL=openbmb/VoxCPM2
# VoxCPM random seed for reproducible voice (optional, defaults to 2028)
PIPECAT_VOXCPM_TTS_SEED=2028

• mimo：小米云端服务，中文识别和合成效果较好，需要 MIMO_API_KEY。

• whisper：本地 Whisper 语音识别，免费，首次启动会自动下载模型。

• kokoro：本地 Kokoro ONNX 语音合成，免费，首次启动会自动下载模型。

• piper：本地 Piper 语音合成，免费，首次启动会自动下载指定音色模型。

• voxcpm：基于 nanovllm-voxcpm 的高性能 TTS 服务，调用 OpenAI 兼容的 /v1/audio/speech 接口，服务端以 48 kHz s16le PCM 流式输出，延迟低。需要先部署 nanovllm-voxcpm 或 vLLM-Omni服务，并通过 PIPECAT_VOXCPM_URL 指定地址。可选项：PIPECAT_VOXCPM_TTS_MODEL（模型名）、PIPECAT_VOXCPM_TTS_SEED（音色随机种子，固定种子可复现同一音色）。音色仍由统一的 PIPECAT_TTS_VOICE 控制，默认 default。

如果切换到 PIPECAT_TTS_PROVIDER=kokoro 且使用 af_heart，请把 PIPECAT_TTS_LANGUAGE 改成 en，否则 Kokoro 的 espeak 后端会报 zh 不支持。

切换传输层

默认 WebRTC。如需使用 Daily 房间，在 .env 中设置：

PIPECAT_RUNNER_TRANSPORT=daily
DAILY_API_KEY=你的Daily_API_Key
DAILY_ROOM_URL=你的Daily房间地址

常见问题

Q: 说话后听到两次回复？ A: Pipeline 中不要放置 LLM 服务。本项目的架构中，AI 客户端（Claude/Codex）是"大脑"，Pipeline 只需要 STT + TTS。

Q: 浏览器界面上看不到 AI 的文字回复？ A: TTS 会消费 LLMTextFrame 并输出音频帧，文字无法到达 UI。agent.py 已修复此问题：speak() 会同时推送文字到 assistant_aggregator 用于 UI 显示。

Q: 如何修改 TTS 音色？ A: 可选音色：mimo_default、冰糖、茉莉、苏打、白桦、Mia、Chloe、Milo、Dean。在 agent.py 的 _create_tts_service() 中修改 voice 参数即可。

更多资源

• Pipecat 文档

• Pipecat Discord

• MCP 协议

• Claude Code 文档