Wavix

Wavix MCP Server

一个 Model Context Protocol 服务，让大模型和 AI Agent 可以直接访问 Wavix 电信平台，涵盖短信/彩信、语音通话、双重身份验证（2FA）、SIP 中继、电话号码管理、10DLC 注册、通话录音、语音分析和计费。

Wavix 是一个全球通信平台，可通过单一 API 发送短信、拨打语音电话并运行 2FA 流程。平台提供免费试用；付费使用按你账户关联的 Wavix 定价方案计费。

使用此 MCP 服务最快的方式是使用其托管端点 https://mcp.wavix.com/mcp：让任何兼容 MCP 的客户端连接到该端点，然后使用 Wavix 账户或 Wavix API 密钥进行连接。如果你需要自托管（例如使用自定义 Wavix 部署、位于防火墙后，或使用专用实例），请参阅自行运行。

目录

• 端点
• 安装 — 使用账户登录、API 密钥、一键安装、Claude Code、Claude Desktop / Web、Cursor、VS Code、Codex CLI、Windsurf
• 自行运行（自托管）
• 示例
• 工具 → TOOLS.md 中的完整目录
• 资源
• 身份验证（最佳实践、令牌泄露时的处理方法）
• 故障排除
• 兼容性与限制
• 支持、贡献、安全、许可证

端点

字段	值
URL	https://mcp.wavix.com/mcp
传输方式	Streamable HTTP
身份验证	使用 Wavix 账户登录（OAuth 2.1），或使用 Authorization: Bearer <api_key>
工具	参见 TOOLS.md
资源	Wavix 文档 + OpenAPI 规范（自动发现）

从 Wavix Console 获取 Wavix API 密钥 → Administration → API keys → Create new。

安装

有两种连接方式，选择客户端支持的方式即可；两者没有优先级之分。

使用 Wavix 账户登录

如果你的 MCP 客户端支持 OAuth（Claude Desktop / Web 及其他支持 OAuth 的客户端），可以不使用 API 密钥进行连接：添加 https://mcp.wavix.com/mcp 连接器，然后在客户端提示时使用 Wavix 账户登录并批准访问。客户端会运行 OAuth 2.1 流程并自行保存令牌，无需粘贴任何内容。你获得的工具权限仅限于你批准的范围以及账户角色允许的范围（参见故障排除）。

使用 API 密钥连接

**开始前：**准备好你的 Wavix API 密钥。

1. 在 https://wavix.com 登录。
2. 打开 Administration → API keys。
3. 点击 Create new（或复制现有密钥）。准备好密钥，稍后将其粘贴以替换下方的 YOUR_API_KEY。

一键安装

⚠️ 以下按钮会在编辑器的 MCP 配置中填入占位令牌 YOUR_API_KEY。 编辑器完成安装后，打开生成的配置，并在发送任何请求之前将占位值替换为真实 API 密钥，否则每次调用都会返回 401 Unauthorized。

**之后如需移除：**打开同一个配置文件（~/.cursor/mcp.json、.vscode/mcp.json，或编辑器对应的配置文件），删除 wavix 条目，或通过编辑器的 MCP / Connectors UI 移除连接器。

Claude Code

claude mcp add --transport http wavix https://mcp.wavix.com/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

使用 claude mcp list 验证，并在会话中使用 /mcp 查看状态。

Claude Desktop / Claude Web

设置 → 连接器 → 添加自定义连接器：

• 名称：Wavix
• URL：https://mcp.wavix.com/mcp
• 传输方式：Streamable HTTP
• 身份验证标头：Authorization: Bearer <api_key>

如需改为通过登录连接，请添加不带身份验证标头的连接器，并在客户端提示时使用 Wavix 账户登录。

Cursor（手动配置）

添加到 ~/.cursor/mcp.json（或项目级 .cursor/mcp.json）：

{
  "mcpServers": {
    "wavix": {
      "url": "https://mcp.wavix.com/mcp",
      "headers": {
        "Authorization": "Bearer <api_key>"
      }
    }
  }
}

Cursor 2.4+ 会显示完整目录；更早的版本最多显示 40 项。

VS Code（手动配置，GitHub Copilot Chat）

在工作区中创建 .vscode/mcp.json（或在用户 settings.json 的 "mcp" 键下添加相同的 servers 对象）：

{
  "servers": {
    "wavix": {
      "type": "http",
      "url": "https://mcp.wavix.com/mcp",
      "headers": {
        "Authorization": "Bearer <api_key>"
      }
    }
  }
}

有关最新架构，请参阅 VS Code MCP 服务指南。

Codex CLI

Codex CLI 支持通过 stdio 使用 MCP。通过 mcp-remote 连接托管服务。编辑 ~/.codex/config.toml：

[mcp_servers.wavix]
command = "npx"
args = [
  "-y",
  "mcp-remote",
  "https://mcp.wavix.com/mcp",
  "--header",
  "Authorization:Bearer ${WAVIX_API_KEY}"
]

[mcp_servers.wavix.env]
WAVIX_API_KEY = "YOUR_API_KEY"

Windsurf / 其他客户端

任何支持带自定义标头的 Streamable HTTP 传输方式的 MCP 客户端都可以使用。请使用：

• URL：https://mcp.wavix.com/mcp
• 标头：Authorization: Bearer <api_key>

**通过 AI Agent 设置？**让 Agent 参考 llms-install.md——这是一份机器可读的安装指南，采用确定性格式提供 URL、标头和各客户端的配置信息，避免模型自行编造端点值。

运行自己的服务

托管服务开箱即用，适合大多数用户。如果你需要连接非公开的 Wavix 部署、在防火墙后运行，或在自己的基础设施中运行，请使用自托管方式。

Docker

docker build -t wavix-mcp-server .
docker run --rm -p 8000:8000 wavix-mcp-server

服务会监听 8000 端口，并在 /mcp 提供 MCP 端点。将客户端指向 http://<host>:8000/mcp。

从源代码运行

git clone https://github.com/Wavix/wavix-mcp-server.git
cd wavix-mcp-server
pip install -e .
wavix-mcp

需要 Python 3.10+。

配置

环境变量	默认值	用途
WAVIX_API_BASE_URL	https://api.wavix.com	覆盖上游 Wavix API 端点（用于内部部署或预发布环境）
OAUTH_ISSUER	未设置	OAuth 2.1 授权服务器的基础 URL。其 JWKS 从 <issuer>/.well-known/jwks.json 读取
OAUTH_RESOURCE	未设置	访问此服务所用的公开基础 URL，用作资源标识符
OAUTH_API_KEY_PASSTHROUGH	true	启用 OAuth 后，仍接受非 OAuth JWT 的 bearer token，并将其转发至上游（API 密钥仍可使用）。设为 false 可要求使用 JWT
MCP_PATH	/mcp	提供 MCP 端点的路径

运行此服务无需 Wavix 凭据——凭据会通过 MCP 客户端的 Authorization: Bearer <api_key> 请求头按请求转发。可自托管此服务的用户有责任在公开服务前，在服务前端终止 TLS（使用 nginx、Caddy 或云负载均衡器）。

OAuth 2.1（可选）

同时设置 OAUTH_ISSUER 和 OAUTH_RESOURCE，即可将此服务设为受 OAuth 2.1 保护的资源。此时，服务会在 /.well-known/oauth-protected-resource<MCP_PATH> 发布 RFC 9728 元数据，根据颁发者的 JWKS 将传入的访问令牌验证为 JWT，并对未通过身份验证的请求 返回 WWW-Authenticate 挑战，指向该元数据。支持 OAuth 的 MCP 客户端会据此自行 运行授权流程，因此用户无需再将 API 密钥粘贴到客户端配置中。

每个令牌必须携带的受众值为 OAUTH_RESOURCE + MCP_PATH，这也是元数据中 发布的 resource 值。实现 RFC 8707 的授权服务器会将客户端的 resource 参数与该字符串进行精确比对，因此两者必须配置一致，包括路径。

启用 OAuth 不会断开使用 Wavix API 密钥进行身份验证的客户端。非有效 OAuth JWT 的 bearer token 会像之前一样未经验证地转发至上游，由 Wavix API 独自负责验证——因此， 现有部署可以为新客户端启用 OAuth，而不会影响已连接的客户端。完全不携带令牌的请求 仍会收到 WWW-Authenticate 挑战，支持 OAuth 的客户端正是通过它发现授权服务器的。 只有通过 OAuth 身份验证的连接会受到作用域过滤；使用 API 密钥的连接可以访问完整的工具集。

设置 OAUTH_API_KEY_PASSTHROUGH=false 可关闭此回退行为，并要求提供有效的 JWT——待停用 API 密钥访问后，可切换到这种严格模式。

如果 OAUTH_ISSUER / OAUTH_RESOURCE 中任意一项未设置，则保持原有行为： 不发布元数据，客户端发送的任何 bearer token 都会未经验证地转发至上游。

示例

可直接用于任何已连接客户端的具体提示词。

以下电话号码（+1 310 555 0100、+44 7700 900123）属于预留测试号段（NANP 555 和 Ofcom 070 09xx）——可直接照抄使用，不会联系到真实用户。

发送事务性 SMS

提示词：“从 +13105550100 向 +447700900123 发送一条 SMS，内容为‘您的验证码是 4821’。”

Agent 会使用 from、to 和 text 调用 sms_and_mms_messages_send。返回消息 ID 和送达状态。

进行双重身份验证

提示词：“通过 SMS 向 +13105550100 发送双重身份验证验证码。我把收到的验证码告诉你后，请检查是否正确。”

Agent 会调用 two_fa_verification_create，等待你提供通过 SMS 收到的验证码，然后调用 two_fa_verification_check。无需编写集成代码，即可用于快速构建无密码流程原型。

查找并购买电话号码

提示词：“查找一个可用的、支持短信功能的美国免费电话号码，将其加入购物车并结账。”

Agent 依次调用 buy_numbers_list（按国家和功能筛选）、cart_add 和 cart_checkout。cart_checkout 首次调用会返回包含号码及费用的预览；再次调用并传入其 confirmation_token 后，才会从账户扣款。

搜索通话记录文本

提示词：“显示昨天所有时长超过两分钟、且来电者提到‘退款’的呼入电话。”

Agent 使用 cdrs_search 搜索转录文本，然后通过 cdrs_get 获取每条结果的完整通话元数据。

获取录音并转录

提示词：“获取通话 abc-123 的录音，让 Wavix 转录，并返回转录文本。”

Agent 调用 call_recording_get_by_call（返回预签名下载 URL）、cdrs_retranscribe，然后轮询 cdrs_transcription_get。

审核账单

提示词：“我们上个月在短信上花了多少钱？开具了哪些发票？”

Agent 调用按类型和日期筛选的 billing_transactions_list，然后调用 billing_invoices_list。MCP 不支持下载发票 PDF——请从 Wavix API 或控制面板获取。

工具

根据 Wavix OpenAPI 规范生成。参数与请求参数和请求正文中的字段一致。显示的工具取决于你在登录时批准的权限，以及账户中启用的功能。

分组	涵盖功能
短信和 MMS	发送、列出和获取消息；发送方 ID；退订
WhatsApp	商业账户；发送方；模板；发送、列出和获取消息
通话控制	发起、接听和结束通话；播放音频；收集 DTMF
通话录音	列出、下载（预签名 URL）和删除
通话流	启动、停止媒体流
通话 Webhook	列出、创建和删除
CDR	列出、获取；搜索转录文本并重新转录
语音分析	转录、获取原始文件
双重验证	创建、检查、取消和重新发送验证；事件
我的号码	列出、更新和释放；短信、语音路由
购买	国家、地区、城市；搜索可用号码
购物车	添加、移除、获取、结账
号码验证器	单个和批量验证
SIP 中继	完整的 CRUD 操作
10DLC	品牌、营销活动、审核、证明材料、事件订阅
个人资料	获取、更新个人资料；账户配置
API 密钥	列出、创建、更新和删除
子账户	列出、创建、获取和更新；交易
账单	交易；列出发票、账单
语音营销活动	触发和获取
Wavix Embeddable（WebRTC）	Widget 令牌 CRUD 操作
链接缩短器	创建短链接；指标

完整工具列表及每项工具的一行说明，请参阅 TOOLS.md。权威来源是 Wavix OpenAPI 规范——客户端始终能看到当前的实时目录。

资源

除了工具外，服务器还会将 Wavix 文档作为 MCP 资源公开，让模型可按需获取权威上下文，而不是依赖先前的知识进行猜测。

URI scheme	内容
wavix://docs/<path>	来自 docs.wavix.com 的文档页面（通过 llms.txt 自动发现）。
wavix://api/openapi.yaml	完整的 Wavix OpenAPI 3.0 规范。

这两个来源——docs.wavix.com 和 Wavix OpenAPI 规范——均公开提供，无需身份验证即可直接浏览。

资源会在调用 resources/read 时按需获取，并在服务器端缓存 1 小时。上游 Bearer 令牌绝不会转发到文档主机，只会转发到 api.wavix.com。

身份验证

托管服务器支持两种连接方式，二者没有优先级之分：

• 使用 Wavix 账户登录（OAuth 2.1）。 适用于支持 OAuth 的客户端。客户端会运行授权流程，用户登录即可；无需存储 API 密钥。访问权限受范围限制，并取决于用户批准的权限以及账户角色允许的权限。请参阅使用 Wavix 账户登录。
• Wavix API 密钥（Bearer）。 适用于任何 Streamable-HTTP 客户端。每个请求都必须包含：

Authorization: Bearer <api_key>

服务器会在每个请求中将此标头转发到 api.wavix.com。此令牌：

• 绝不会被记录到日志中；
• 绝不会在跨主机重定向时转发（例如预签名的 S3 下载 URL）；
• 绝不会发送到文档主机。

如果客户端跟随 call_recording_get_by_call、speech_analytics_file_get 或 ten_dlc_brand_evidence_get 返回的预签名下载 URL，请直接获取该 URL，不要携带 Authorization 标头。

最佳实践

• 为 MCP 使用专用 API 密钥。 在 https://wavix.com → Administration → API keys 创建单独的 API 密钥（也可以在另一个会话中通过 api_keys_create 工具创建）。这样即可撤销 MCP 的访问权限，而不会影响其他集成。

• 定期轮换。 将 API 密钥视为任何生产环境机密：按计划轮换，并在怀疑密钥泄露时立即轮换。

• 不要将 API 密钥提交到 git。 MCP 客户端配置很容易被意外提交，从而使令牌出现在提交历史和 CI 日志中。大多数客户端都支持在标头值中使用 ${env:VAR} 替换——请将 API 密钥存储在环境变量或操作系统的钥匙串中，并在配置中引用该变量。为确保安全，请将常见的客户端配置路径添加到项目的 .gitignore 中：

  .cursor/mcp.json
  .vscode/mcp.json
  claude_desktop_config.json
  .claude/mcp.json
  .codex/config.toml
  

凭据泄露时的处理方式

如果你使用 API 密钥连接：

1. 立即在 Wavix Console 中停用或删除该密钥（或调用 api_keys_delete）。
2. 通过 api_keys_create 或 Console 创建替代密钥。
3. 更新客户端配置并重新连接。

如果你通过登录 Wavix 账户连接：

1. 在 Wavix 门户网站的授权管理页面撤销连接。该页面会列出你授权的连接，并可撤销你选择的连接，从而使该连接的令牌失效。此方式不涉及 API 密钥。
2. 重新连接并再次登录。

无论哪种情况，都请检查 billing_transactions_list 和 cdrs_list，确认是否存在异常活动。

故障排查

症状	可能原因 / 解决方法
任意工具返回 401 Unauthorized	身份验证失败。使用 API 密钥时：缺少 Authorization: Bearer … 标头，或密钥无效或已停用——请在 Wavix Console 中验证。使用账户登录时：会话 / 令牌已过期或被撤销，或登录尚未完成——请重新连接并再次登录。
工具返回 download_url，而不是文件本身	这是预期行为。录音、语音分析和 10DLC 证据端点会返回预签名 URL（参见身份验证）。直接获取该 URL，不要附带 Authorization 标头。
客户端只显示部分目录	较旧的客户端会限制每个服务的工具数量。请升级（Cursor 2.4+、最新版 VS Code、最新版 Claude）。
使用 Wavix 账户登录后，可用工具变少	这是预期行为。账户登录会按范围筛选——你能使用获批范围和账户角色允许的工具，而不是完整目录。使用 API 密钥连接时，可看到全部工具。若要扩大可用范围，请在登录时批准更多范围（受你的角色限制），或使用包含这些范围的 API 密钥连接。
README 中列出的工具出现 Tool not found	本地客户端可能缓存了旧版工具列表。请重启客户端，或移除并重新添加服务。
4xx 错误且包含 errors 数组	Wavix API 返回验证错误。请检查 errors，并参照相关的 wavix://docs/* 页面或 OpenAPI 规范。
无法连接到服务	请确认 DNS 正常，并且可以向 mcp.wavix.com:443 发起出站 HTTPS 连接。
Agent 意外调用了具有破坏性的工具	大多数客户端都可以要求在调用工具前进行确认——请启用该设置，并改用专用 MCP API 密钥（参见最佳实践）。

兼容性与限制

• 兼容支持 Streamable HTTP 传输的任何 MCP 客户端（Claude Desktop / Web / Code、Cursor 2.4+、VS Code、Windsurf、自定义 MCP SDK），以及带有 MCP 客户端适配器的任何 Agent 框架。
• 每个标注了 destructiveHint 的工具，以及 call_webhooks_create、sip_trunks_update 和 sub_accounts_update，都分两步执行：首次调用会返回预览和一次性 confirmation_token（有效期为 5 分钟）；只有在再次使用相同参数和该令牌调用工具时，操作才会执行。任何 MCP 客户端都可以执行此流程；无需客户端支持确认。
• 较旧的客户端可能会限制每个服务的工具数量；请升级到较新版本以访问完整目录。
• 速率限制和使用费用遵循你的 Wavix 账户方案。请参阅 Wavix 定价。

更新日志

随着 Wavix OpenAPI 规范不断演进，托管服务会持续更新；新工具会自动出现，现有工具的参数也可能增加可选字段。本仓库的文档变更记录在 Releases 下。对于影响工具输入或身份验证的重要行为变更，我们会在此处和 Wavix 发布说明中同时发布通知。

支持

• 产品文档：https://docs.wavix.com
• API 参考：https://docs.wavix.com/api-reference
• 问题 / 反馈：[email protected]

贡献

本仓库提供源代码，但不接受外部贡献。拉取请求会自动关闭，Issues / Discussions 已禁用。请将错误报告、功能请求和反馈发送至 [email protected]。详情请参阅 CONTRIBUTING.md。

如果你发现底层 FastMCP 框架存在错误，请在上游仓库报告。

安全

如需报告安全漏洞，请发送邮件至 [email protected]，并将主题设为 Security: <short summary>，不要创建公开 Issue。详情请参阅 SECURITY.md。

许可证

MIT © Wavix