Pipecat MCP Server

 

Pipecat MCP服务器

Pipecat MCP服务器公开 语音相关 和 屏幕截图 MCP兼容客户端的工具，但是 它本身不提供麦克风或扬声器访问.

音频输入/输出由 独立的音频/视频传输例如：

• Pipecat游乐场 （本地浏览器UI）
• 每日 （WebRTC室）
• 电话供应商 （Twilio、Telnyx等）

像Cursor、Claude Code和Codex这样的MCP客户端控制代理，但它们不是音频设备。 要听、说或看，您必须通过其中一个音频传输连接。

🧭 入门

先决条件

• Python 3.10或更高版本
• 紫外线 包管理器

默认情况下，语音代理使用 Groq 云服务（Whisper STT+Orpheus TTS）。集 GROQ_API_KEY 开始吧。看 语音预设 下面是包括完全本地选项的替代配置。

安装

克隆此存储库并从源安装：

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

这将安装 pipecat-mcp-server 从本地签出命令，因此您所做的任何更改都可以立即使用。

备注：上游PyPI包(uv tool install pipecat-ai-mcp-server)从安装官方版本 pipecat ai/pipecat mcp服务器此分叉包括额外的DDD架构改进、端口冲突检测和扩展的测试覆盖范围。

运行服务器

启动服务器：

pipecat-mcp-server

服务器使用 标准 默认情况下，它被设计为由MCP客户端（Claude Code、Cursor、Codex）启动。MCP客户端调用 start 工具，语音代理的音频游乐场可在 http://localhost:7860.

🎙️ 语音预设

集 VOICE_PRESET 在STT/TTS组合之间切换：

例子：

export VOICE_PRESET=cartesia
export DEEPGRAM_API_KEY=your-key
export CARTESIA_API_KEY=your-key
pipecat-mcp-server

情绪标签处理

代理进程 俄耳甫斯风格的情感标签 根据预设不同：

• 格罗克：标签如 [cheerful], `` 本地传递
• 笛卡尔：括号标签转换为Cartesia SSML([cheerful] -> ``)
• deepgram/本地/kokoro：所有情绪标记都被删除

自动审批权限

对于免提语音对话，您需要自动批准工具权限。否则，您的代理将提示确认，这会中断对话流程。

⚠️ 警告：启用广泛权限的风险由您自行承担。

安装Pipecat技能（推荐）

这 管道技巧 提供更好的语音对话体验。它要求在更改文件之前进行口头确认，在使用广泛权限时增加一层安全性。

或者，告诉你的经纪人 Let's have a voice conversation在这种情况下，代理人在做出更改之前不会要求口头确认。

🖥️ 屏幕截图与分析

屏幕截图允许您将屏幕（或特定窗口）流式传输到配置的传输，并要求代理帮助处理它看到的内容。

例如：

• *“捕获我的浏览器窗口”* --开始流式传输该窗口
• *“是什么导致了这个错误？”* --代理分析屏幕并帮助调试
• *“这个UI看起来怎么样？”* --获得对设计的反馈

支持的平台：

• macOS --使用ScreenCaptureKit进行真正的窗口级捕获（不受重叠窗口的影响）
• Linux（X11） --使用Xlib进行窗口和全屏捕获

💻 MCP客户端：克劳德代码

添加MCP服务器

使用stdio传输注册MCP服务器：

claude mcp add pipecat --transport stdio pipecat-mcp-server --scope user

范围选项：

• local：存储在 ~/.claude.json，仅适用于您的项目
• user：存储在 ~/.claude.json，适用于所有项目
• project：存储在 .mcp.json 在您的项目目录中

自动审批权限

创建 .claude/settings.local.json 在您的项目目录中：

{
  "permissions": {
    "allow": [
      "Bash",
      "Read",
      "Edit",
      "Write",
      "WebFetch",
      "WebSearch",
      "mcp__pipecat__*"
    ]
  }
}

这将授予bash命令、文件操作、web获取和搜索以及所有Pipecat MCP工具的权限，而不会提示。看 可用工具 如果你需要授予更多权限。

开始语音对话

1. 将Pipecat技能安装到 .claude/skills/pipecat/SKILL.md
2. 启动Pipecat MCP服务器。
3. 连接到音频传输（请参阅 🗣️ 连接到语音代理 在......下面
4. 跑 /pipecat.

💻 MCP客户端：光标

添加MCP服务器

通过编辑注册MCP服务器 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "pipecat": {
      "url": "http://localhost:9090/mcp"
    }
  }
}

自动审批权限

去 Auto-Run 代理设置并将其配置为 Run Everything.

开始语音对话

1. 将Pipecat技能安装到 .claude/skills/pipecat/SKILL.md （光标支持克劳德技能位置）。
2. 启动Pipecat MCP服务器。
3. 连接到音频传输（请参阅 🗣️ 连接到语音代理 在......下面
4. 在一个 新游标代理，跑 /pipecat.

💻 MCP客户端：OpenAI Codex

添加MCP服务器

注册MCP服务器：

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

自动审批权限

如果你开始 codex 在版本控制项目中，系统会询问您是否允许Codex在未经批准的情况下处理该文件夹。说 Yes，这增加了以下内容 ~/.codex/config.toml.

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

开始语音对话

1. 将Pipecat技能安装到 .codex/skills/pipecat/SKILL.md.
2. 启动Pipecat MCP服务器。
3. 连接到音频传输（请参阅 🗣️ 连接到语音代理 在......下面
4. 跑 $pipecat.

🗣️ 连接到语音代理

语音代理启动后，您可以根据服务器的配置使用不同的方法进行连接。

Pipecat游乐场（默认）

当未向指定参数时 pipecat-mcp-server 命令，服务器使用Pipecat的本地游乐场。通过打开连接http://localhost:7860在您的浏览器中。

您还可以运行一个可以远程连接的ngrok隧道：

ngrok http --url=your-proxy.ngrok.app 7860

每日预制

您还可以使用 每日 并通过Daily房间访问您的代理，这很方便，因为您可以在没有隧道的任何地方访问。

首先，安装具有Daily依赖关系的服务器：

uv tool install -e ".[daily]"

然后，设置 DAILY_API_KEY 环境变量添加到您的Daily API键和 DAILY_ROOM_URL 转到您所需的每日房间URL，并传递 -d 论证到 pipecat-mcp-server.

export DAILY_API_KEY=your-daily-api-key
export DAILY_ROOM_URL=your-daily-room

pipecat-mcp-server -d

通过打开您的每日房间URL进行连接（例如。， https://yourdomain.daily.co/room)在您的浏览器中。Daily Prebuild提供了一个即用型视频/音频接口。

LiveKit 的

LiveKit 的 提供低延迟WebRTC房间，类似于Daily，但可自托管。

export LIVEKIT_URL=wss://your-livekit-server
export LIVEKIT_API_KEY=your-api-key
export LIVEKIT_API_SECRET=your-api-secret

pipecat-mcp-server --transport livekit

电话

要通过电话连接，请通过 -t -x 哪里 是其中之一 twilio, telnyx, exotel，或 plivo，以及 ` 是您的ngrok隧道域（例如。， your-proxy.ngrok.app`).

首先，启动你的ngrok隧道：

ngrok http --url=your-proxy.ngrok.app 7860

然后，使用您的ngrok URL和所选电话提供商所需的环境变量运行Pipecat MCP服务器。

提里奥

export TWILIO_ACCOUNT_SID=your-twilio-account-sid
export TWILIO_AUTH_TOKEN=your-twilio-auth-token

pipecat-mcp-server -t twilio -x your-proxy.ngrok.app

配置您的提供商的电话号码以指向您的ngrok URL，然后拨打您的号码进行连接。

🧪 测试

该项目包括一个在没有完整Pipecat依赖树的情况下运行的测试套件。测试模拟重型框架导入，同时保留真实类型层次结构 isinstance() 检查。

pip install pytest pytest-asyncio
python -m pytest tests/ -v

测试包括：情感标签处理、VisionProcessor捕获/传递、机器人命令路由和MCP工具包装器。

📚 接下来是什么？

• 切换语音预设：设置 VOICE_PRESET 尝试不同的STT/TTS组合
• 更改运输方式：配置为Daily、LiveKit、Twilio、WebRTC或其他传输方式
• 添加到您的项目：将此用作支持语音的MCP工具的模板
• 了解更多：查看 Pipecat的文档 用于高级功能
• 得到帮助：加入 Pipecat的不和 与社区建立联系