Chamade

@chamade/mcp-server

适用于 Chamade 的 MCP（Model Context Protocol）服务——Chamade 是一个语音和聊天网关，可让你的 AI Agent 加入 Discord、Microsoft Teams、Google Meet、Telegram、SIP、Zoom、Nextcloud Talk、Slack 和 WhatsApp 上的会议与私信。

推荐的语音方案是使用托管 STT/TTS，并自带密钥。 只需在控制面板中填入你自己的 ElevenLabs / Deepgram / OpenAI / Cartesia API 密钥，Chamade 就会使用该密钥在其一侧运行完整的语音处理流程。转录内容会作为 call_transcript 事件传入，chamade_call_say 则会在会议中发言。Chamade 不收取费用；你只需向服务提供商付费。你的 Agent 始终完全由文本驱动。

已经有想继续使用的语音处理流程（OpenAI Realtime、LiveKit Agents、Pipecat、Deepgram Voice Agent 或手动级联）？Chamade 也会通过双向 WebSocket 提供通话的原始 PCM 音频——音频由你提供，传输由 Chamade 负责，语音处理层由你运行。无论采用哪种模式，控制工具都相同。

Discord、Telegram、Slack、WhatsApp（包括语音留言）和 Nextcloud Talk 的私信与会议聊天均开箱支持文件附件。使用 chamade_file_upload_url 生成无需身份验证的预签名上传 URL，然后在 chamade_dm_chat 或 chamade_call_chat 的 attachments 中传入返回的 file_id。传入的文件会以 Chamade 签名 URL 的形式通过 chamade_inbox 到达——你的 Agent 可以直接用 curl 获取，无需额外身份验证。Teams 和 Meet 的支持已完成代码开发，但须等待相应平台认证完成后才能启用。

Chamade 目前处于早期访问阶段：免费、无需订阅、没有配额限制。

v4：托管 MCP + 轻量 stdio shim

Chamade MCP 服务现已托管于 https://mcp.chamade.io/mcp/，并使用 Streamable HTTP 传输。 这里是唯一事实来源——所有工具、所有资源和所有推送事件都在此提供。

• 如果你的 MCP 客户端支持 Streamable HTTP（较新版本的 Claude Desktop、Claude Code、Cursor、Windsurf 等），可直接将其配置为连接托管端点。你不需要这个 npm 包。
• 如果你的 MCP 客户端仅支持 stdio，请安装这个包。从 v3 起，它是一个约 160 行的封装器，会在底层启动 mcp-remote，将 stdio 桥接到托管 HTTP 端点。工具相同、推送事件相同、延迟相同。由于没有并行的 stdio 实现，因此不会产生偏差。

v4 中的变更

v4 是一项服务端线格式变更，shim 会自动适配。主要内容如下，详情见 docs/AGENTS.md：

• Channels 现在称为 Agents。 每个 bearer 的作用域保持不变；在线格式和工具描述中，统一使用 agent 这一名称。
• account_id 是规范的关联键。 在 chamade_dm_chat、chamade_call_join、事件负载和回复 XML 标签属性中，均以相同方式使用。
• 事件负载 v2。 data 包含 account_id、from、from_name（已移除 sender_* 字段），以及预先填充的 agent_context.{accounts, active_calls} 快照，因此 Agent 无需额外往返，就始终知道当前所处的上下文。
• 支持显式指定目标的 XML 标签。 回复 XML 现在可以指定当前回复上下文之外的对话 / 通话（<dm platform=…>、<call_say call_id=…> 等），以便发起跨目标操作。
• 自动附加 MCP。 原生支持将 MCP 作为工具的提供方（OpenAI Responses、Anthropic Managed Agents、Foundry）会预先注入 Chamade MCP 服务，并为每个 Agent 配置独立的 bearer。

此软件包的早期版本（v2.x 及更早版本）提供了完整的原生 stdio 服务，使用 TypeScript 在本地针对 Chamade REST API 实现了 13 个工具。v3+ 将其替换为 shim——请升级，以免同时维护两个逐渐出现差异的接口。

快速开始

选项 A — 直接使用 HTTP（首选）

如果你的客户端支持 Streamable HTTP，可以完全跳过此软件包：

{
  "mcpServers": {
    "chamade": {
      "type": "http",
      "url": "https://mcp.chamade.io/mcp/",
      "headers": {
        "Authorization": "Bearer chmd_..."
      }
    }
  }
}

选项 B — stdio shim（此软件包）

适用于仅支持 stdio 的客户端：

{
  "mcpServers": {
    "chamade": {
      "command": "npx",
      "args": ["-y", "@chamade/mcp-server@3"],
      "env": {
        "CHAMADE_API_KEY": "chmd_..."
      }
    }
  }
}

必须设置 CHAMADE_API_KEY。 前往 https://chamade.io/dashboard → API keys 获取有效密钥，并粘贴完整的 chmd_… 值（前缀后至少 40 个字符）。如果环境变量缺失、为空，或仍包含 chmd_... 之类的占位符，shim 会拒绝启动，而不是静默回退到 OAuth——该回退路径会陷入刷新与撤销的循环，并非此服务可行的身份验证方式。

配置

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%/Claude/claude_desktop_config.json（Windows）。使用上面的选项 A 或 B。

Claude Code

在项目根目录的 .mcp.json 中配置。为获得最佳体验，请使用选项 A（直接使用 HTTP）。

若要接收实时推送事件（转录、收到的私信、来电、WhatsApp dm_delivered 刷新），每次启动 Claude Code 时都要加上 channel 标记：

claude --dangerously-load-development-channels server:chamade --continue

Claude Code 要求对尚未加入 Anthropic 允许列表的 MCP channels 进行逐次启动的客户端主动选择；这并不危险，只是研究预览期间对实验性 channels 的标准主动选择方式。server: 后的服务名称必须与 .mcp.json 中的键一致。如果不加此标记，工具仍可正常使用，但推送事件会被静默忽略——你必须轮询 chamade_inbox 和 chamade_call_status 才能查看新活动。

Cursor / Windsurf / OpenClaw

格式相同。路径因客户端而异：.cursor/mcp.json、~/.codeium/windsurf/mcp_config.json、~/.openclaw/config.json。如果客户端支持 HTTP，请使用选项 A；否则使用选项 B。

工具

工具	描述
chamade_call_join	加入语音会议（平台 + meeting_url）。
chamade_call_say	在会议中通过 TTS 大声朗读文本。
chamade_call_chat	在会议中发送文本聊天消息。可选的 attachments: [{file_id} | {url} | {bytes_b64, name, mime}] 用于随文本发送文件；两者都设置时，text 会作为说明文字。每个附件上限为 25 MB。
chamade_call_status	获取通话状态和新增的转录行（增量模式）。
chamade_call_accept	接听响铃中的来电（SIP 等）。
chamade_call_refuse	拒接响铃中的来电。
chamade_call_typing	在会议聊天中发送正在输入指示。
chamade_call_leave	挂断并离开会议。
chamade_call_list	列出所有正在进行的通话。
chamade_inbox	查看私信对话（Discord、Telegram、Teams、WhatsApp、Slack、NC Talk）。内联显示 WhatsApp 24 小时窗口状态。收到的文件附件会作为每条消息的 attachments[] 提供，并附带 Chamade 签名 URL。
chamade_dm_chat	按平台发送私信。可选的 attachments: [{file_id} | {url} | {bytes_b64, name, mime}] 用于发送文件；text 会作为说明文字。在 WhatsApp 的 24 小时窗口之外，会返回 202 并排队处理，同时自动发送重新互动模板。
chamade_dm_typing	按平台在私信中发送正在输入指示。
chamade_file_upload_url	生成一个有效期为 5 分钟的预签名上传 URL。使用 shell / agent curl -F file=@path <url>，不要添加 auth header（URL 本身即为授权凭据），然后在后续发送的 attachments: [{file_id}] 中传入返回的 file_id。任何较大的本地文件都建议采用此方式——通过 shell 流式上传可让工具调用保持精简，无需将每个 base64 字符都计入模型的输出预算。
chamade_account	查看账户状态、套餐、额度 / 配额以及各平台的就绪状态（包括每个平台的 files 布尔值）。

资源

URI 模板	描述
chamade://calls/{call_id}/transcript	实时转录。每次读取仅返回自上次读取以来新增的行（增量模式）。频道模式的客户端还会收到每条新行的推送通知。

频道模式（推送事件）

频道模式会将私信消息、SIP 来电、转录行、通话状态变更以及 WhatsApp dm_delivered 刷新事件直接推送到 Agent 的上下文中，无需轮询。

**服务端——无需配置。**托管的 Chamade MCP 服务在初始化握手期间始终声明 experimental.claude/channel 功能。v2.x 的 --channel 参数 / CHAMADE_CHANNEL=1 环境变量已移除。

**客户端——Claude Code 需要在每次启动时添加标志。**Claude Code 只会处理来自已明确选择启用的 MCP 服务的 notifications/claude/channel：

claude --dangerously-load-development-channels server:chamade --continue

每次启动都必须添加。否则，Chamade 工具仍可正常工作，但客户端会静默丢弃推送事件——Agent 必须轮询 chamade_inbox 和 chamade_call_status 才能查看新活动。

其他 MCP 客户端（Claude Desktop、Cursor、Windsurf）目前没有频道接收器，会静默忽略推送通知。它们仍可通过轮询模式使用 chamade_inbox，并搭配 last_message_cursor 和可选的 wait 进行长轮询。

环境变量（仅限 shim）

只有 stdio shim 会使用这些变量。直接 HTTP 配置中的所有内容都在 JSON 中。

变量	必填	默认值	描述
CHAMADE_API_KEY	是	—	来自 chamade.io/dashboard 的 API 密钥（chmd_*，熵值 ≥ 40 个字符）。shim 会在启动时验证格式；遇到占位符或缺少值时会以状态码 1 退出；没有 OAuth 回退机制。
CHAMADE_URL	否	https://chamade.io	Chamade 实例 URL。shim 会自动推导 MCP 端点：https://chamade.io → https://mcp.chamade.io/mcp/，https://dev.chamade.io → https://mcp.dev.chamade.io/mcp/。
CHAMADE_MCP_URL	否	—	显式指定 MCP 端点。除非你正在运行自定义代理，否则请勿设置。

v2.x 的 --channel CLI 标志会被静默接受，以保持向后兼容，但它不起作用——v3 中始终启用 channel 模式。

支持的平台

• Discord — 语音频道（共享机器人或自带机器人）、文本、文件（发送和接收，25 MB）
• Microsoft Teams — 语音会议 + 文本私信；需要在仪表板上连接 OAuth。文件功能已准备好代码，但需通过 AppSource 认证后才能使用。
• Google Meet — 语音（audio_in）+ 聊天文本；需要在仪表板上连接 OAuth （见下方说明）。文件功能已准备好代码，但需通过 Google OAuth 验证后才能使用。
• Telegram — 私信文本 + 文件（发送和接收）。不支持语音。
• Zoom — 语音 + 会议聊天，传入会议 URL（等待 Zoom Marketplace 审批——可申请测试者访问权限）。不支持文件。
• SIP / Phone — 仅语音，传入电话号码或 SIP URI。不支持文件。
• Nextcloud Talk — 语音 + 文本 + 文件（任何插件版本都支持发送；接收需要插件版本 ≥ 2.4.0）
• WhatsApp — 私信文本 + 文件（发送和接收，包括以原始音频形式发送的语音消息）。不支持语音通话。

⚠️ Google Meet 语音——Beta 版限制。 Meet 的实时音频捕获依赖 Google 的 Meet Media API，该 API 目前处于 Developer Preview 阶段。每位会议参与者都必须单独注册，否则音频捕获会失败。日历集成和会议内聊天对所有人都能正常使用。对于生产环境中的语音使用场景，建议优先选择 Teams、Discord、Nextcloud Talk 或 SIP。

工作原理

Agent (Claude Desktop, Cursor, …)
  │ MCP (Streamable HTTP, Authorization: Bearer chmd_*)
  ▼
mcp.chamade.io                       (hosted by Chamade)
  │
  ▼
Chamade API                           (chamade.io)
  │
  ▼
Maquisard bridge                      (transports audio; forwards to your
                                       STT/TTS provider when BYOK preset set)
  │
  ▼
Discord / Teams / Meet / …

使用选项 B（stdio shim）时，客户端不直接使用 HTTP；shim 作为传输适配器，位于客户端和服务之间：

Agent (stdio-only client)
  │ stdio JSON-RPC
  ▼
@chamade/mcp-server@3                 (this package, ~160 LOC)
  │ spawns
  ▼
mcp-remote                            (local subprocess)
  │ Streamable HTTP, Bearer chmd_*
  ▼
mcp.chamade.io                        (hosted)

开发

npm install
npm run dev     # runs with tsx (hot reload, src/index.ts)
npm run build   # compiles to dist/
npm test        # unit tests for deriveMcpUrl + buildRemoteArgs

shim 本身非常精简（见 src/index.ts）。完整的 MCP 工具行为测试位于 Chamade 上游仓库的 tests/e2e/test_mcp_http.py 中，该测试直接调用托管服务——这是工具语义的权威依据。

文档

• MCP 服务文档 — 各主流客户端的设置方法
• 推送模式文档 — 实时推送事件的工作原理（有状态会话）
• Agents — bearer × 平台范围限定（每个密钥 / OAuth 客户端对应一个 Agent）
• 完整 API 参考 — 全部工具和端点，采用适合大模型的格式
• 设置指南 — 面向 Agent 的逐步入门指南

问题与反馈

• Bug 或功能请求：提交 issue
• 直接联系：[email protected]
• 应用内反馈：每个 Chamade 仪表板都有“Send feedback”按钮

许可证

MIT — 详见 LICENSE。