Vobiz

Vobiz MCP 服务

适用于 Vobiz 的官方 Model Context Protocol 服务。它让 Claude 和任何其他 MCP 客户端都能在你的 Vobiz 账户上执行实际操作：

• 拨打和控制语音电话、发起电话会议，并将通话音频流式传输给 AI Agent
• 构建 VobizXML IVR
• 读取通话记录和录音
• 管理电话号码、SIP 中继、凭据、IP 允许列表、SIP 端点、语音应用和子账户
• 查看计费交易
• 发送 SMS、MMS 和 RCS 消息
• 安排提醒电话和唤醒电话（托管连接器）
• 一步完成呼叫并播放音频或朗读文本：使用 make_call 搭配 say / play（托管连接器）

它还附带 Vobiz Agent Skills，让模型在执行操作前了解每款 Vobiz 产品的工作方式。

工具	114 个，分属 13 个工具集：通话、通话中控制、电话会议、媒体（音频流、录音、号码释放、计费）、记录、IVR/XML、账户和号码、配置（应用、号码购买、SIP 中继）、SIP 端点和凭据、子账户、消息（SMS/MMS/RCS、退订）、技能，以及使用你自己的音频拨打提醒电话（托管连接器）
提示词	17 个：每项 Vobiz 技能对应一个，例如 vobiz-voice-xml、vobiz-sip-trunking
资源	vobiz://skills/index 和 vobiz://skills/{name}（支持补全）
传输方式	stdio（npx）、适用于单个账户的 Streamable HTTP、通过 OAuth 2.1 提供的托管式多租户 Streamable HTTP
安全性	默认禁用呼叫、消息发送和账户变更。呼叫、消息、购买、转接、配置和删除操作都需要 confirm: true；已发起通话的控制操作（按键音、播放、语音、静音）无需再次确认。呼叫和消息发送设有速率限制，并支持幂等操作。VOBIZ_READ_ONLY 和 VOBIZ_TOOLSETS 可限制模型可见的内容。

如果你需要的是文档搜索，而非账户操作，请使用托管的 Vobiz Docs MCP 服务（https://www.vobiz.ai/docs/mcp）。这两个服务可以搭配使用。

“到……时给我打电话”

使用托管连接器（https://mcp.vobiz.ai/mcp）时，你可以说 “明天早上 6 点叫醒我” 或 “3 点给我打电话，提醒我去看牙医”。客户端只需调用一次 schedule_reminder_call，之后由服务完成其余工作：在指定时间使用你的 Vobiz 号码拨打电话、朗读消息，并允许你按 1 稍后提醒、按 2 确认，或按 9 停止。无人接听时会重试。无需让聊天窗口保持开启。

登录时，你可以选择 完全访问、个人助手（仅允许向你自己的号码拨打提醒电话，并可查看余额、号码和通话状态）或 只读，然后输入你自己的号码、可选的主叫号码和时区。使用 list_reminder_calls、get_reminder_call 和 cancel_reminder_call 管理提醒。运营人员请参阅 docs/HOSTING.md。

“打给我并播放这个”

在托管连接器上，“拨打 +919876543210 并播放我的闹钟” 或 “拨打 +919876543210 并说‘您的餐桌已准备好’” 都会调用一次 make_call，并传入 say（文本）和／或 play（音频库中的文件，或直接的 https .mp3／.wav 链接）。连接器托管通话脚本：通话会播放或朗读内容，然后挂断（loop: 0 会重复播放音频，直到你挂断）。无法播放 Pixabay、YouTube、Spotify 或 SoundCloud 等网页；请提供直接文件链接，或先将文件添加到音频库。参见 docs/TOOLS.md。

在提醒电话中播放你自己的音频

你可以说 “用这个 MP3 作为我的闹钟” 或 “让我录制这条消息”。你的音频会在通话开始时、语音消息之前播放。你可以通过以下三种方式将其添加到私人音频库：

• 上传页面。 create_audio_upload_link 会生成一个一次性链接（有效期为 15 分钟）。打开链接以选择或拖放文件，或按 录制，通过麦克风录音（最长 5 分钟），然后为其命名。
• 直接从聊天中上传。 如果你附加了文件，且助手能够运行代码，它会自行通过同一个链接上传文件。
• 公开链接。 粘贴 https 链接，助手会使用 import_audio_from_url 将其保存。

然后说 “使用音频 Morning alarm”，助手会将该名称作为 audio 传递给 schedule_reminder_call。支持 MP3、WAV、M4A、OGG、WEBM、AAC 和 FLAC；每个文件最多 15 MB、5 分钟。使用 list_audio 查看文件，使用 delete_audio 删除文件。运营者请参见 docs/HOSTING.md。

目录

• 你可以提出的请求
• 五步连接 Claude
• 安装（所有客户端：docs/INSTALL.md）
• 工具
• 技能、提示词和资源
• 安全模型
• 配置
• 运行模式
• 托管连接器（OAuth）
• 隐私政策
• 开发
• 故障排除
• 相关内容

可以询问的内容

询问 Claude	执行的操作
“我的 Vobiz 余额是多少？有多少通电话正在进行？”	get_account_balance、get_concurrency、list_live_calls
“显示昨天拨打至 +91 80 1234 5678 的未接来电”	list_call_records，按日期、号码和 hangup_cause 筛选
“用我在班加罗尔的号码拨打 +919876543210，并向对方读出这条提醒”	list_phone_numbers → 你确认 → make_call → speak_text → get_call_status
“明天 6 点叫醒我，并提醒我乘坐 7:10 的火车”（托管版）	你确认 → schedule_reminder_call；服务会在你所在时区的 06:00 呼叫你
“建立一个 IVR：按 1 转销售，按 2 转支持”	get_vobiz_skill vobiz-voice-xml → generate_answer_xml
“从我的美国号码向 +14155550123 发送‘您的订单已发货’”	preview_message_cost → 你确认 → send_message → get_message
“谁回复了我们上一条群发短信？”	list_broadcasts、list_messages direction=in、list_conversations
“阻止 +14155550123 接收后续消息”	add_opt_out（你确认）
“我的 Webhook 指向哪里？”	查询所有应用和 SIP 中继的 list_webhooks
“为我的 LiveKit Agent 设置 SIP 中继”	get_vobiz_skill vobiz-sip-trunking → create_sip_trunk（你确认）
“在 sales-standup 会议中将除主持人外的所有人静音”	get_conference → mute_conference_member
“将此通话的音频流式传输到我的 Agent：wss://agent.example.com/ws”	start_audio_stream（你确认）
“允许办公室 IP 203.0.113.10 访问中继，并为 PBX 添加 SIP 用户”	add_ip_acl_entry、create_trunk_credential（你确认）
“为孟买团队创建子账户，并向他们发送 KYC 链接”	create_sub_account、create_sub_account_kyc_session（你确认）
“我们上周花了多少钱？”	使用日期范围调用 list_transactions
“如何迁移我的 Plivo 集成？”	vobiz-plivo-migration 提示词

五步连接 Claude

适用于 claude.ai、Claude Desktop 和 Claude 移动应用。无需安装任何内容。

1. 复制凭据。 在 Vobiz 控制台概览页，复制你的 Auth ID（MA_…，子账户则为 SA_…）和 Auth Token。
2. 打开连接器。 在 Claude 中，前往 Settings → Connectors → Add custom connector。Team 和 Enterprise 计划的 Owner 可在 Admin settings → Connectors 下添加一次，然后每位成员连接自己的 Vobiz 账户。
3. 添加服务。 将其命名为 Vobiz，输入 https://mcp.vobiz.ai/mcp，高级 OAuth 字段留空，然后点击 Add。
4. 连接并登录。 点击 Connect。在 Vobiz 登录页面粘贴你的 Auth ID 和 Auth Token，可选择勾选 Read-only access，然后点击 Allow access。返回 Claude 后即已连接。
5. 开始使用。 在新聊天中，于工具菜单启用 Vobiz，然后提问：“我的 Vobiz 余额是多少？现在有多少通电话正在进行？”

目的	操作
在只读和完全访问权限之间切换	Settings → Connectors → Vobiz → Disconnect，然后再次点击 Connect 并更改 Read-only access
断开连接	Settings → Connectors → Vobiz → Disconnect
一次撤销所有应用的访问权限	在 Vobiz 控制台轮换你的 Auth Token

Claude 在执行拨打电话、发送消息或更改账户的工具前会先询问，而服务对每项操作都要求你确认。托管连接器不提供购买号码的功能。

安装

你需要拥有 Vobiz 账户，并从 Vobiz 控制台概览页获取 Auth ID 和 Auth Token。完整指南（包含适用于每种客户端的配置文件）请参阅 docs/INSTALL.md。

一步连接（托管版，推荐）

客户端	一步操作	然后
Claude（网页、Desktop、移动端）	Settings → Connectors → Add custom connector → https://mcp.vobiz.ai/mcp	点击 Connect 并登录（5 步完成连接）
Claude Code	claude mcp add --transport http vobiz https://mcp.vobiz.ai/mcp	运行 /mcp，选择 vobiz 并登录
Claude Code（插件：服务 + 技能）	/plugin install vobiz --marketplace vobiz-ai/Vobiz-MCP-Server	按提示输入 Auth ID 和 Auth Token
Claude Desktop（本地扩展）	从最新版本打开 vobiz-mcp-v1.4.3.mcpb	输入 Auth ID 和 Auth Token
OpenAI Codex（命令行、IDE、应用）	codex mcp add vobiz --url https://mcp.vobiz.ai/mcp	Vobiz 登录页面会在浏览器中打开；稍后若要重新登录，请运行 codex mcp login vobiz
ChatGPT	Plugins → + → Add custom MCP server → https://mcp.vobiz.ai/mcp	登录，然后使用 @Vobiz
Gemini CLI	gemini mcp add -s user --transport http vobiz https://mcp.vobiz.ai/mcp	运行 /mcp auth vobiz
Cursor	添加到 Cursor	在 Cursor 的 MCP 设置中点击 Connect
VS Code / GitHub Copilot	添加到 VS Code	启动服务并登录
Windsurf / Devin	devin mcp add -s user vobiz https://mcp.vobiz.ai/mcp	devin mcp login vobiz
Cline	cline mcp add vobiz https://mcp.vobiz.ai/mcp --transport http --yes	选择 Authorize OAuth
Goose	打开 goose://extension?url=…（链接）	登录
Zed、JetBrains、Warp、LM Studio、Continue	将 { "url": "https://mcp.vobiz.ai/mcp" } 添加为服务（指南）	登录

所有远程选项都会在 Vobiz 页面上通过 OAuth 登录，因此不会将 Auth Token 写入配置文件。若要改为在自己的机器上运行服务，请使用下方的本地选项。

在本地运行

本地选项会通过 npx 在你的计算机上运行服务，需要 Node.js 22.9 或更高版本。

客户端	安装
Claude（网页、桌面端、移动端）	设置 → 连接器 → 添加自定义连接器 → https://mcp.vobiz.ai/mcp
Claude Desktop 扩展	打开最新版本中的 vobiz-mcp-v1.4.3.mcpb
Claude Code	/plugin install vobiz --marketplace vobiz-ai/Vobiz-MCP-Server（MCP 服务 + 技能）
OpenAI Codex	codex mcp add vobiz --env VOBIZ_AUTH_ID=MA_XXXXXXXX --env VOBIZ_AUTH_TOKEN=YOUR_AUTH_TOKEN -- npx -y @vobiz/[email protected]
Gemini CLI	gemini extensions install https://github.com/vobiz-ai/Vobiz-MCP-Server
Cursor	一键安装
VS Code / Copilot	一键安装
Goose	goose configure → 添加扩展 → npx -y @vobiz/[email protected]（深层链接）
Windsurf、Zed、Cline、JetBrains、Continue、LM Studio、Warp、ChatGPT	docs/INSTALL.md

其他 MCP 客户端：

{
  "mcpServers": {
    "vobiz": {
      "command": "npx",
      "args": [
        "-y",
        "@vobiz/[email protected]"
      ],
      "env": {
        "VOBIZ_AUTH_ID": "MA_XXXXXXXX",
        "VOBIZ_AUTH_TOKEN": "YOUR_AUTH_TOKEN"
      }
    }
  }
}

在 env 中添加 VOBIZ_ENABLE_CALLS、VOBIZ_ENABLE_MESSAGING 或 VOBIZ_ENABLE_PROVISIONING 并将其设为 "true" 后，才能启用通话、消息和账户变更功能。

要自托管远程连接器：docker run -p 3000:3000 -e VOBIZ_HOSTED_URL=https://mcp.example.com -e VOBIZ_HOSTED_SECRET="$(openssl rand -hex 32)" ghcr.io/vobiz-ai/vobiz-mcp:v1.4.3（docs/HOSTING.md）。

工具

每个工具都有 title、输入验证和注解：readOnlyHint: true 或 destructiveHint: true，以及 idempotentHint 和 openWorldHint。结果为 structuredContent，同时也会以文本形式发送相同的 JSON。docs/TOOLS.md 列出了所有输入，内容由注册表生成。

工具集	只读	需要 confirm: true 的写入操作	无需二次确认的写入操作
calls	get_call_status、list_live_calls	make_call、end_call	send_dtmf
call_control		transfer_call、hold_call、unhold_call、start_recording	play_audio、stop_audio、speak_text、stop_speaking、stop_recording
conferences	list_conferences、get_conference	end_conference、end_all_conferences、kick_conference_member、hangup_conference_member、start_conference_recording	mute_conference_member、unmute_conference_member、deafen_conference_member、undeafen_conference_member、play_audio_to_conference_member、stop_audio_to_conference_member、stop_conference_recording
media	list_audio_streams、get_audio_stream、list_transactions、list_transaction_types	start_audio_stream、delete_recording、release_phone_number、cancel_number_release、assign_number_to_subaccount、unassign_number_from_subaccount	stop_audio_stream
records	get_call_details、list_call_records、get_call_recording、list_recordings
voice_xml	generate_answer_xml、get_gather_result、list_webhook_events、list_webhooks	gather_dtmf
account	get_account_details、get_account_balance、get_concurrency、list_phone_numbers、get_phone_number_details、get_number_health、list_sip_trunks、get_sip_trunk
provisioning	list_applications、get_application、search_available_numbers	create_application、update_application、delete_application、buy_phone_number、update_phone_number、create_sip_trunk、update_sip_trunk、delete_sip_trunk
sip	list_sip_endpoints、get_sip_endpoint、list_trunk_credentials、list_ip_acl_entries、list_origination_uris	create_sip_endpoint、update_sip_endpoint、delete_sip_endpoint、create_trunk_credential、update_trunk_credential、delete_trunk_credential、add_ip_acl_entry、update_ip_acl_entry、delete_ip_acl_entry、create_origination_uri、update_origination_uri、delete_origination_uri
subaccounts	list_sub_accounts、get_sub_account、get_sub_account_kyc_status	create_sub_account、update_sub_account、delete_sub_account、create_sub_account_kyc_session
messaging	list_messaging_numbers、preview_message_cost、list_messages、get_message、list_conversations、get_conversation_messages、list_broadcasts、get_broadcast、check_opt_out、list_opt_outs	send_message、add_opt_out、remove_opt_out
reminders（仅托管版）	list_reminder_calls、get_reminder_call、list_audio	schedule_reminder_call、cancel_reminder_call、delete_audio	create_audio_upload_link、import_audio_from_url
skills	list_vobiz_skills、get_vobiz_skill

选择工具。 对某些客户端来说，114 个工具数量不少。只加载所需工具：

• VOBIZ_TOOLSETS=calls,call_control,records,skills 仅注册这些组。
• VOBIZ_READ_ONLY=true 仅保留只读工具。

密钥。 SIP 密码、凭据密钥和子账户令牌始终会被隐藏。请在 Vobiz 控制台中重置或复制它们。

需要托管。 gather_dtmf、get_gather_result、list_webhook_events、hold_call 和 unhold_call 需要 Vobiz 能够访问此服务。使用配置了 VOBIZ_PUBLIC_URL 的单账户 HTTP 模式来调用这些工具。

错误。 错误是 MCP 工具错误（isError: true），格式如下：

{ "ok": false, "error": "not_allowed", "message": "…what happened and what to do…", "retryable": false, "http_status": 400, "hint": "…" }

错误类型。

• 输入与访问：invalid_input、missing_credentials、auth_failed、forbidden、not_found、insufficient_balance
• 限制与可用性：rate_limited、timeout、network_error、service_unavailable
• 服务开关与策略：calls_disabled、messaging_disabled、provisioning_disabled、confirmation_required、not_allowed、spending_limit
• 幂等性：duplicate_blocked、idempotency_conflict、in_progress、outcome_unknown
• 其他：call_not_active、opted_out、unsupported、internal_error

通话结果。 通话结果会添加 outcome（answered、busy、no_answer、rejected、invalid_number、unreachable、cancelled 等）以及典型的 SIP 代码。

技能、提示词和资源

这 17 个 Vobiz Agent 技能随软件包一同提供（skills/），并通过三种方式公开，因此可在所有客户端中使用：

界面	使用方法
工具	list_vobiz_skills 会返回每项技能的名称、描述和章节。get_vobiz_skill { name, section? } 会返回完整技能或其中一个章节。
提示词	每项技能都是一个提示词，并带有可选的 task 参数。在 Claude Code 中，输入 /mcp__vobiz__vobiz-voice-xml build an IVR for a clinic。
资源	vobiz://skills/index 和 vobiz://skills/{name}，支持名称补全。

技能列表：

• 语音与通话： vobiz-api、vobiz-voice-calls、vobiz-voice-xml、vobiz-audio-streams、vobiz-cdr
• 活动与报告： vobiz-campaign-planner、vobiz-reports
• 号码与基础设施： vobiz-phone-numbers、vobiz-sip-trunking、vobiz-applications-endpoints
• AI 与消息： vobiz-ai-voice-agents、vobiz-sms、vobiz-whatsapp
• 账户与合作伙伴： vobiz-sub-accounts、vobiz-partner-api
• 迁移与范围界定： vobiz-plivo-migration、vobiz-forward-deployed-engineer

这些技能来自 Vobiz 文档仓库。使用 npm run skills:sync [path/to/.mintlify/skills] 刷新。

安全模型

以下所有规则均由服务端强制执行，不会交由模型处理。

防护措施	默认设置
外呼	关闭（VOBIZ_ENABLE_CALLS）
发送消息、更改退订状态	关闭（VOBIZ_ENABLE_MESSAGING）
购买或释放号码；更改中继、SIP 端点、凭据、IP 允许列表、应用和子账户；删除录音	关闭（VOBIZ_ENABLE_PROVISIONING）。购买操作还要求 VOBIZ_MAX_NUMBER_COST > 0。
明确确认	当 MCP 客户端支持征询时，呼叫、消息、转接、保持、录音、音频流、购买、号码释放和其他账户更改，都必须由用户在服务端提示词中批准，提示词会注明目标号码、URL 主机或费用；拒绝后不会执行任何操作。其他客户端使用 confirm: true，由模型代表用户设置（由模型声明）。MCP 客户端还会对每个破坏性工具操作进行提示。
幂等性	idempotency_key 会重放首次结果，而不会重复执行。VOBIZ_DUPLICATE_CALL_WINDOW_SEC 时间窗口内的相同呼叫会被拒绝。结果未知时，操作会保持阻止状态。使用共享存储（基于 Firestore 的托管连接器）时，所有副本共享记录以及呼叫/消息上限；在多租户模式下，VOBIZ_IDEMPOTENCY_FILE 会被忽略。
呼叫限制	目标国家和屏蔽前缀（也适用于服务端构建的每个 <Dial> 号码），以及通话时长、每分钟和每小时呼叫次数、并发数上限。检查开始前会预留并发名额，因此同时发出的请求不会超出上限。预付费账户设有余额下限。
消息限制	每次发送的收件人数、每分钟和每小时的消息数、收件人所在国家。发送方必须是账户中的消息号码。系统会遵守退订状态。
号码购买	费用上限、每日上限、余额预检查、已持有号码检查
呼叫控制 URL	仅限 https，且仅允许已批准的主机（托管模式：任何公共主机）。URL 中不得包含凭据。
租户隔离	账户仅从凭据中获取。任何工具都不接受账户 ID。
密钥	身份验证令牌、SIP 密码和其他密钥都会从结果中删去。日志仅记录路由模板和状态码，绝不记录电话号码或令牌。
不可信内容	消息正文、来电者姓名和回调载荷均为数据，而非指令。返回这些内容的工具会将每个条目标记为 untrusted: true，并添加顶层的 notice 和 untrusted_fields；其他字段保持不变。

配置

所有设置均为环境变量。除凭据（以及托管模式下的托管设置）外，其他变量均为可选项。.env.example 列出了所有变量并附有注释。

区域	变量（默认值）
工具选择	VOBIZ_TOOLSETS（全部），VOBIZ_READ_ONLY（false）
凭据	VOBIZ_AUTH_ID，VOBIZ_AUTH_TOKEN，VOBIZ_BASE_URL（https://api.vobiz.ai），VOBIZ_ENV（development），VOBIZ_TIMEOUT_MS（15000），VOBIZ_LOG_LEVEL（info），VOBIZ_DEFAULT_PAGE_SIZE（20）
呼叫	VOBIZ_ENABLE_CALLS（false），VOBIZ_DEFAULT_ANSWER_URL，VOBIZ_VERIFY_CALLER_ID（true），VOBIZ_ALLOWED_COUNTRY_CODES（任意），VOBIZ_BLOCKED_PREFIXES，VOBIZ_ALLOWED_DESTINATIONS，VOBIZ_ALLOWED_CALLER_IDS，VOBIZ_MAX_CALL_DURATION_SEC（600），VOBIZ_MAX_CALLS_PER_MINUTE（5），VOBIZ_MAX_CALLS_PER_HOUR（30），VOBIZ_MAX_CONCURRENT_CALLS（3），VOBIZ_CHECK_BALANCE（true），VOBIZ_MIN_BALANCE（0），VOBIZ_BALANCE_CURRENCY（主钱包），VOBIZ_DUPLICATE_CALL_WINDOW_SEC（120），VOBIZ_IDEMPOTENCY_FILE
消息	VOBIZ_ENABLE_MESSAGING（false），VOBIZ_MESSAGING_ALLOWED_COUNTRY_CODES（任意），VOBIZ_MAX_RECIPIENTS_PER_SEND（10），VOBIZ_MAX_MESSAGES_PER_MINUTE（20），VOBIZ_MAX_MESSAGES_PER_HOUR（200），VOBIZ_VERIFY_SENDER（true）
账户变更（号码、中继、SIP、应用、子账户、录音）	VOBIZ_ENABLE_PROVISIONING（false），VOBIZ_MAX_NUMBER_COST（0 = 不购买），VOBIZ_MAX_NUMBER_PURCHASES_PER_DAY（1）
URL	VOBIZ_ALLOWED_URL_HOSTS，VOBIZ_ALLOW_ANY_URL_HOST（false）
链接	VOBIZ_CONSOLE_URL，VOBIZ_PRIVACY_URL，VOBIZ_DOCS_URL，VOBIZ_DOCS_MCP_URL（公开的 Vobiz URL）
单账户 HTTP	PORT（3000），HOST（127.0.0.1），VOBIZ_HTTP_SECRET，VOBIZ_PUBLIC_URL，VOBIZ_REMOTE_ALLOW_CALLS（false），VOBIZ_WEBHOOK_SIGNATURE（require），VOBIZ_ANSWER_TEXT
托管连接器	VOBIZ_HOSTED_URL，VOBIZ_HOSTED_SECRET，VOBIZ_ACCESS_TOKEN_TTL_SEC（3600，最大值 86400），VOBIZ_REFRESH_TOKEN_TTL_SEC（2592000），VOBIZ_ALLOWED_ORIGINS（https://claude.ai,https://claude.com,https://chatgpt.com,https://chat.openai.com），VOBIZ_HOSTED_EXCLUDED_TOOLS
托管连接器 OAuth	VOBIZ_TRUSTED_CLIENTS（无；redirect-host=Display Name），VOBIZ_LOGIN_MAX_PER_IP（10），VOBIZ_LOGIN_MAX_PER_AUTH_ID（10），VOBIZ_TRUSTED_EGRESS_CIDRS（Anthropic 公布的范围），VOBIZ_TRUSTED_EGRESS_URL

运行模式

| 模式 | 命令 | 适用场景 | |---|---|---|---| | stdio | npx -y @vobiz/mcp（或 node dist/index.js） | Claude Desktop、Claude Code、Cursor 及其他在单个账户上使用的本地客户端 | | 单账户 HTTP | npx -y @vobiz/mcp http（或 npm run start:http） | 通过路径密钥提供 Streamable HTTP，适用于托管 IVR 流程、收集输入和签名 Webhook | | 托管多租户 | npx -y @vobiz/mcp hosted（或 npm run start:hosted、Docker） | 公共连接器：每位用户通过 OAuth 登录，且只能操作自己的账户 | | 控制面板 | npm run dashboard → http://127.0.0.1:5178 | 基于相同工具构建的只读本地浏览器视图 |

单账户 HTTP 端点

| 路径 | 用途 | 身份验证 | |---|---|---|---| | /mcp/<VOBIZ_HTTP_SECRET> | Streamable HTTP MCP | 路径密钥 | | /sse/<secret>、/message/<secret> | 面向旧版客户端的传统 SSE MCP | 路径密钥 | | /xml/flow/<id> | 托管 XML（接听、转接、保持、拨号） | Vobiz 签名 + 128 位 ID | | /xml/gather/<id> | Gather Digits 回调；返回后续 XML | Vobiz 签名 + ID | | /webhooks/vobiz | 接听、挂断和状态回调 | Vobiz 签名 | | /answer | 静态 <Speak> XML | 无 | | /health | 存活状态 | 无 |

回调签名。 回调会通过 X-Vobiz-Signature-V3 = base64(HMAC-SHA256(auth_token, URL-without-query + "." + nonce)) 进行验证。V2 可作为后备方案接受，且比较采用恒定时间算法。重复使用的 nonce 会被拒绝，重复事件只会存储一次。

托管连接器（OAuth）

vobiz-mcp hosted 在一个进程中集成了完整的 OAuth 2.1 授权服务器和 MCP 资源服务器。它专为 Claude 的连接器目录构建，并适用于任何远程 MCP 客户端。

登录流程：

1. Claude 在未提供令牌的情况下调用 POST /mcp。服务器返回 401，并附带 WWW-Authenticate: Bearer resource_metadata=".../.well-known/oauth-protected-resource/mcp"。
2. Claude 读取受保护资源元数据（RFC 9728，resource = <VOBIZ_HOSTED_URL>/mcp）和授权服务器元数据（RFC 8414）。AS 元数据声明支持 PKCE S256、动态客户端注册（RFC 7591）和客户端 ID 元数据文档。
3. Claude 注册自身或使用其 CIMD URL，然后打开 /authorize。用户输入自己的 Auth ID 和 Auth Token，并选择完整访问、个人助手或只读，同时提供用于提醒电话的自有号码、来电显示号码和时区。服务器使用 Vobiz 验证凭据，然后重定向回去并提供一次性代码。
4. /token 将代码（经 PKCE 验证）兑换为有效期为 1 小时的访问令牌和有效期为 30 天的刷新令牌。

令牌处理：

• 令牌使用 AES-256-GCM 封装，因此无需凭据数据库，任意数量的副本都可以共用 VOBIZ_HOSTED_SECRET。
• 每个请求仅在已登录的账户上运行，并设有账户级速率限制和幂等性保护。
• 在 Vobiz 控制台轮换 Auth Token 会立即撤销该账户的所有令牌。

服务器卡片。 GET https://mcp.vobiz.ai/mcp/server-card（别名 /.well-known/mcp/server-card.json）提供一张 MCP 服务器卡片，其中包含服务器名称、版本、Streamable HTTP 端点和支持的协议版本，供连接前发现服务器的客户端和扫描器使用。该卡片公开可访问，缓存时间为 1 小时，且不列出任何工具；工具列表会在登录后通过 tools/list 获取。

工具排除项。 托管连接器不会提供购买商品或需要服务器托管某个账户回调的工具。默认列表为 buy_phone_number、gather_dtmf、get_gather_result、list_webhook_events、hold_call 和 unhold_call，你可以通过 VOBIZ_HOSTED_EXCLUDED_TOOLS 更改此列表。系统会根据 VOBIZ_ALLOWED_ORIGINS 检查浏览器的 Origin 标头。

部署、DNS、扩缩容和提交至目录的说明，请参阅 docs/HOSTING.md 和 docs/PUBLISHING.md。

隐私政策

此服务由 Vobiz（Ilaimitado Private Limited）发布。完整政策请见 https://www.vobiz.ai/privacy。

处理的内容：

• 您的 Vobiz Auth ID 和 Auth Token，仅用于验证您对 Vobiz API 的请求。
• MCP 客户端发送的工具参数，例如电话号码、消息文本和通话设置。
• 返回给客户端的 Vobiz API 响应。

存储的内容：

• **本地模式：**凭据保存在您的环境或 OS 密钥链中。幂等性记录保存在内存中；如果您设置了 VOBIZ_IDEMPOTENCY_FILE，则保存在该文件中。
• 托管模式（https://mcp.vobiz.ai/mcp）：连接器不会存储任何对话内容。您的 Vobiz Auth ID 和 Auth Token 仅保存在加密（AES-256-GCM）、会过期的令牌中：MCP 客户端持有的访问令牌和刷新令牌，以及提醒电话待处理期间排队的呼叫任务。存储内容如下：

项目	位置	保留期限
通话、消息和号码购买的幂等性记录（键、请求指纹、工具结果）	Firestore	最长 24 小时
通话和消息的速率计数器（按账户、按分钟和小时统计）	Firestore	保留至统计窗口结束（最长 1 小时）
OAuth 会话（刷新令牌系列：ID、时间戳、Auth ID 的哈希值；刷新令牌会轮换并检测重复使用）和已使用的授权码	Firestore	每个会话最长 90 天；授权码 5 分钟后过期
提醒电话（目标号码、消息文本、时区、主叫号码、计划时间和每次尝试的结果）	Firestore	作为您的提醒历史记录保留；cancel_reminder_call 会停止待处理的提醒电话
音频库文件及其名称	私有 Cloud Storage 存储桶，以 Auth ID 的哈希值为路径	保留至您使用 delete_audio 删除

**绝不会做的事：**不会读取您的对话历史、记忆或文件。不会将您的数据用于广告，也不会出售或与第三方共享。

**日志：**日志包含路由模板、HTTP 状态码和耗时。绝不会包含令牌、消息文本或电话号码。

**保留期限：**通话记录、录音和消息会根据 Vobiz 条款保留在您的 Vobiz 账户中（https://www.vobiz.ai/terms）。

**联系方式：**[email protected]

开发

git clone https://github.com/vobiz-ai/Vobiz-MCP-Server.git
cd Vobiz-MCP-Server
npm ci
cp .env.example .env        # placeholders only; fill in your own credentials
npm run check               # type-check, build, mocked tests
npm run test:live           # live read-only smoke test with .env credentials (calls/messages/purchases forced off)
npm run test:live:hosted    # live OAuth flow + hosted tools against the real API (no messages sent)
npm run inspector           # MCP Inspector against dist/index.js
npm run docs:tools          # regenerate docs/TOOLS.md
npm run skills:sync         # refresh bundled skills from the docs repository

代码布局：

• 工具位于 src/tools/{calls,control,conferences,media,records,account,voice,provisioning,sip,subaccounts,messaging}.ts 中。每个文件对应一个工具集，并在 src/server.ts 中注册。
• 技能位于 src/skills.ts 中。
• 防护措施位于 src/policy.ts、src/idempotency.ts 和 src/outcomes.ts 中。
• VobizXML 生成代码位于 src/xml.ts，托管流程位于 src/flows.ts，回调验证代码位于 src/webhooks.ts。
• 传输方式位于 src/index.ts（stdio）、src/http.ts（单账户）和 src/hosted.ts（OAuth 多租户）中。

测试：

• 模拟测试不会访问网络，也不会执行通话、发送消息或购买号码。
• CI 会运行 lint、build、Node 22 和 24 上的测试、npm audit、.mcpb 清单检查以及软件包试运行。
• 发布由标签驱动（v1.2.3）。软件包会发布到 npm（附带 provenance）和 MCP Registry，并附上 .mcpb 包，同时推送 Docker 镜像（参见 docs/PUBLISHING.md）。

故障排除

症状	修复方法
missing_credentials / auth_failed	设置或轮换 VOBIZ_AUTH_ID / VOBIZ_AUTH_TOKEN。在托管模式下，重新连接连接器。
查询账户详情时出现 forbidden	查看账户详情需要主账户（MA_）凭据。子账户可查询余额、并发数和号码。
calls_disabled / messaging_disabled / provisioning_disabled	启用相应功能（通过环境变量或桌面扩展设置）。
confirmation_required	模型必须先询问你，然后使用 confirm: true 重试调用。
not_allowed	目标号码或收件人所在国家/地区、被屏蔽的前缀、允许列表、账户中未登记的发件人或来电显示号码，或未经批准的 URL 主机
rate_limited	服务器限制（每分钟、每小时、并发数、消息数）或账户的 CPS 限制。请等待后重试。
duplicate_blocked	在 VOBIZ_DUPLICATE_CALL_WINDOW_SEC 时间窗口内发起了相同呼叫。如果确实需要再次呼叫，请传入新的 idempotency_key。
outcome_unknown	请勿重试。检查 list_live_calls、list_call_records 或 list_messages。
gather 或 hold 出现 unsupported	使用 VOBIZ_PUBLIC_URL 运行单账户 HTTP 模式。
回调因 401 被拒绝	VOBIZ_PUBLIC_URL 必须与 Vobiz 实际发起呼叫的 URL 完全一致。尝试设置 VOBIZ_WEBHOOK_SIGNATURE=verify_if_present。
托管登录提示链接已过期	登录页面的有效期为 15 分钟。请从客户端重新开始连接。

相关项目

• Vobiz CLI（GitHub、文档）：运行 vobiz mcp install <client>，即可将此服务添加到 Claude Code、Cursor、Codex、VS Code、Gemini CLI、Windsurf、Zed 或 Claude Desktop。默认使用托管连接器进行 OAuth 登录。
• Vobiz Agent Skills（GitHub、文档）：此处包含的相同技能，经过打包，可供任何加载技能的 Agent 使用。

由 Vobiz 团队打造

Vobiz 是全球可编程电话平台，提供 SIP 中继、语音 API、SMS、WhatsApp 和 AI 语音 Agent 集成，覆盖 130 多个国家/地区。

支持： [email protected] · 文档 · 问题反馈 · 贡献指南 · 安全 · 行为准则

许可证

MIT © Vobiz