Wavix

官方

Wavix是一个全球通信平台，提供语音、短信、双因素认证和电话号码的API。我们的MCP服务器将这些功能引入AI代理和代理工作流中。

GitHub

你可以用 Wavix MCP 做什么？

发送事务性短信 — 通过 sms_and_mms_messages_send 请求发送带有自定义文本和发送方号码的短信。
运行双因素认证验证 — 使用 two_fa_verification_create 和 two_fa_verification_check 创建并检查用于无密码登录流程的验证码。
查找并购买号码 — 按国家/功能搜索可用号码，加入购物车，并通过 buy_numbers_list、cart_add 和 cart_checkout 完成结算确认。
搜索通话记录 — 按通话时长和转录中的关键词查找通话，然后通过 cdrs_search 和 cdrs_get 丰富完整的元数据。
转录通话录音 — 使用 call_recording_get_by_call、cdrs_retranscribe 和 cdrs_transcription_get 获取通话录音、请求转录并轮询结果。
审计账单 — 通过 billing_transactions_list 和 billing_invoices_list 按类型和日期筛选列出交易和发票。

文档

Wavix MCP 服务器

一个模型上下文协议服务器，让 LLM 和 AI 代理直接访问 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 控制台 → 管理 → API 密钥 → 新建 获取 Wavix API 密钥。

安装

两种连接方式 —— 选择您的客户端支持的一种；两者没有优劣之分。

使用 Wavix 账户登录

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

使用 API 密钥连接

开始之前： 获取您的 Wavix API 密钥。

登录 https://wavix.com。
打开 管理 → API 密钥。
点击新建（或复制现有密钥）。请妥善保管 —— 您需要将其粘贴到下方 YOUR_API_KEY 的位置。

一键安装

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

后续移除： 打开相同的配置文件（~/.cursor/mcp.json、.vscode/mcp.json 或您编辑器的等效文件），删除 wavix 条目，或通过编辑器的 MCP / 连接器界面移除该连接器。

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 代理进行设置？ 将您的代理指向 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 令牌并向上游转发（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 受保护资源。然后它会发布 RFC 9728 元数据，地址为 /.well-known/oauth-protected-resource<MCP_PATH>，将传入的访问令牌作为 JWT 对照签发方的 JWKS 进行验证，并对未认证的请求返回指向该元数据的 WWW-Authenticate 质询。支持 OAuth 的 MCP 客户端会利用此机制自行运行授权流程，因此用户无需再将 API 密钥粘贴到客户端配置中。

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

启用 OAuth 不会切断使用 Wavix API 密钥进行身份验证的客户端。非有效 OAuth JWT 的 bearer 令牌会像之前一样未经验证地向上游转发，由 Wavix API 作为唯一权威 —— 因此现有部署可以为新客户端启用 OAuth，而不会影响已连接的客户端。完全不携带令牌的请求仍会收到 WWW-Authenticate 质询，这使支持 OAuth 的客户端能够发现授权服务器。只有 OAuth 认证的连接会进行范围过滤；API 密钥连接可以看到完整的工具面。

设置 OAUTH_API_KEY_PASSTHROUGH=false 可放弃该回退机制并要求有效的 JWT —— 这是在 API 密钥访问退役后应切换到的严格模式。

将 OAUTH_ISSUER / OAUTH_RESOURCE 中的任何一个留空，则保持之前的行为：不发布元数据，客户端发送的任何 bearer 令牌都会未经验证地向上游转发。

示例

可直接粘贴到任何已连接客户端中的具体提示词。

下方的电话号码（+1 310 555 0100、+44 7700 900123）位于保留测试号段（NANP 555 和 Ofcom 070 09xx）—— 可放心逐字复制，无法通过这些号码联系到真实用户。

发送事务性短信

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

代理调用 sms_and_mms_messages_send，参数为 from、to 和 text。返回消息 ID 和投递状态。

运行 2FA 验证

提示词：“通过短信向 +13105550100 发送 2FA 验证码。当我告诉您收到的验证码时，请检查其是否正确。”

代理调用 two_fa_verification_create，等待您分享通过短信收到的验证码，然后调用 two_fa_verification_check。适合在无需编写集成代码的情况下原型化无密码流程。

查找并购买电话号码

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

代理串联调用 buy_numbers_list（按国家和功能筛选）、cart_add 和 cart_checkout。cart_checkout 首先返回包含号码和费用的预览，仅当使用其 confirmation_token 再次调用时才会向账户收费。

搜索通话记录

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

代理使用 cdrs_search 搜索转写内容，然后通过 cdrs_get 丰富每条结果的完整通话元数据。

获取录音并转写

提示词：“获取通话 abc-123 的录音，请 Wavix 转写，并返回转写内容。”

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

审计计费

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

代理调用按类型和日期筛选的 billing_transactions_list，然后调用 billing_invoices_list。下载发票 PDF 本身不通过 MCP 暴露 —— 请从 Wavix API 或控制台获取。

工具

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

分组	覆盖范围
短信和彩信	发送、列出、检索消息；发送者ID；退订
WhatsApp	商业账户；发送者；模板；发送/列出/检索消息
呼叫控制	开始/接听/结束通话；播放音频；收集DTMF
通话录音	列出、下载（预签名URL）、删除
通话流媒体	开始/停止媒体流
通话Webhooks	列出、创建、删除
CDRs	列出、检索；转录搜索和重新转录
语音分析	转录、检索原始文件
2FA	创建/检查/取消/重发验证；事件
我的号码	列出、更新、释放；短信/语音路由
购买	国家、地区、城市；可用号码搜索
购物车	添加、移除、检索、结账
号码验证器	单个和批量验证
SIP中继	完整CRUD
10DLC	品牌、活动、审核、证据、事件订阅
个人资料	获取/更新个人资料；账户配置
API密钥	列出、创建、更新、删除
子账户	列出、创建、获取、更新；交易
计费	交易；列出发票/账单
语音活动	触发和检索
Wavix可嵌入（WebRTC）	小部件令牌CRUD
链接缩短器	创建短链接；指标

参见 TOOLS.md 获取完整工具列表及一行描述。权威来源是 Wavix OpenAPI规范 — 您的客户端始终看到当前实时目录。

资源

除工具外，服务器还将Wavix文档作为MCP 资源暴露，使模型能够按需获取权威上下文，而不是依赖先前知识进行猜测。

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

两个来源 — docs.wavix.com 和 Wavix OpenAPI规范 — 均公开可用，无需认证即可直接浏览。

资源在 resources/read 时惰性获取，并在服务器端以1小时TTL缓存。上游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 → 管理 → API密钥（或通过 api_keys_create 工具本身，从另一个会话）创建单独的API密钥。这样您可以在不影响其他集成的情况下撤销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密钥连接：

在Wavix控制台中，立即停用或删除该密钥（或调用 api_keys_delete）。
通过 api_keys_create 或控制台创建替换密钥。
更新客户端配置并重新连接。

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

从Wavix门户的授权管理页面撤销连接，该页面列出您授权的连接并撤销您选择的连接 — 这将使该连接的令牌失效。不涉及API密钥。
重新连接并再次登录。

无论哪种情况，请检查 billing_transactions_list 和 cdrs_list 是否有异常活动。

故障排除

症状	可能原因/修复
任何工具返回 `401 Unauthorized`	认证失败。使用API密钥：`Authorization: Bearer …` 标头缺失，或密钥无效/未激活 — 在Wavix控制台中验证。使用账户登录：您的会话/令牌已过期或被撤销，或登录未完成 — 重新连接并再次登录。
工具返回 `download_url`，而非文件本身	预期行为。录音、语音分析和10DLC证据端点返回预签名URL（参见认证）。直接获取URL，不要携带 `Authorization` 标头。
客户端仅显示部分目录	较旧的客户端对每个服务器有工具数量上限。升级（Cursor 2.4+、最新VS Code、最新Claude）。
使用Wavix账户登录后可用工具减少	预期行为。账户登录受范围过滤 — 您只能获得已批准范围和账户角色允许的工具，而非完整目录。API密钥连接可看到完整工具面。要扩大范围，请在登录时批准更多范围（受角色限制）或使用携带这些范围的API密钥连接。
本README中列出的工具返回 `Tool not found`	本地客户端可能正在缓存旧工具列表。重启客户端，或移除并重新添加服务器。
带有 `errors` 数组的4xx错误	Wavix API的验证错误。检查 `errors`；交叉参考相关 `wavix://docs/*` 页面或OpenAPI规范。
无法访问服务器	确认DNS和到 `mcp.wavix.com:443` 的出站HTTPS。
代理意外调用破坏性工具	大多数客户端可以要求在工具调用前确认 — 启用该设置并轮换到专用MCP API密钥（参见最佳实践）。

兼容性与限制

兼容任何支持 Streamable HTTP 传输的MCP客户端（Claude Desktop / Web / Code、Cursor 2.4+、VS Code、Windsurf、自定义MCP SDK）以及任何带有MCP客户端适配器的代理框架。
每个标注了 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
问题/反馈：support@wavix.com

贡献

本仓库为 源代码可用 但 不接受外部贡献。拉取请求自动关闭，Issues / Discussions 已禁用。请将错误报告、功能请求和反馈发送至 support@wavix.com。参见 CONTRIBUTING.md 了解详情。

如果您在底层 FastMCP 框架中发现错误，请在上游报告。

安全

要报告安全漏洞，请发送电子邮件至 support@wavix.com，主题为 Security: <short summary>，而不是公开问题。参见 SECURITY.md 了解详情。