Vonage API Bindings MCP Server

Vonage API MCP 服务

可用工具

此 MCP 服务通过以下工具提供对各种 Vonage API 功能的访问：

类别	工具名称	描述
账户管理	balance	获取 Vonage 账户余额
	list-applications	列出与 API 密钥关联的所有应用及其配置和功能
	create-application	创建一个指定名称的 Vonage 应用
	list-purchased-numbers	列出与账户关联的电话号码及其元数据
号码管理	search-available-numbers	搜索 Vonage 在特定国家/地区提供的可购买电话号码
	link-number-to-vonage-application	将已拥有的号码关联到指定的 Vonage 应用
报告	get-records-report	从 Vonage Reports API 获取活动记录（按日期或 ID 查询）
消息与通信	SMS	使用 Vonage 发送 SMS 消息
	whatsapp-send-text	通过 WhatsApp 发送文本消息
	whatsapp-send-text-with-sms-failover	发送 WhatsApp 文本消息，并在失败时自动切换到 SMS
	rcs-send-text	通过 RCS 发送文本消息
	rcs-send-text-with-sms-failover	发送 RCS 文本消息，并在失败时自动切换到 SMS
	outbound-voice-message	使用 Vonage 发送语音消息
数据可视化	make-chart	根据检索到的数据创建图表

使用示例

查看账户余额

Can you check my Vonage account balance?

列出电话号码

Can you list out the numbers that I own for Vonage?

搜索可购买的号码

Can you search for available Vonage numbers to purchase in the US?

也可以按特定条件搜索：

Can you search for available Vonage numbers in the US with SMS and VOICE features?

Can you search for available numbers in GB starting with pattern "44207*"?

列出应用

Can you list out the applications on my account?

创建新应用

Can you create a new Vonage application called "My Chat App"?

也可以让系统建议一个名称：

Can you create a new Vonage application?

获取记录报告

按日期范围查询：

Can you get a report of all outbound SMS sent over the last week?

按指定 ID 查询：

Can you get the report for Voice Call ID 1234-abcd-5678-efgh?

发送 SMS

Can you send an SMS to +1234567890 with the message "Hello from Vonage!"?

发送 WhatsApp 消息

Can you send a WhatsApp message to +1234567890 with the message "Hello from Vonage over WhatsApp!"?

发送带 SMS 故障转移的 WhatsApp 消息

Can you send a WhatsApp message with SMS failover to +1234567890 saying "Hello from Vonage with failover!"?

发送 RCS 消息

Can you send an RCS message to +1234567890 with the message "Hello from Vonage via RCS!"?

发送带 SMS 故障转移的 RCS 消息

Can you send an RCS message with SMS failover to +1234567890 saying "Hello from Vonage RCS with fallback!"?

生成图表

Please create a chart showing all the outbound SMS sent over the last week.

设置 MCP 服务

• VS Code
• Cursor
• Windsurf
• Claude Desktop

MCP 服务的配置应如下所示。

"vonage-mcp-server-api-bindings": {
    "type": "stdio",
    "command": "npx",
    "args": [
        "-y",
        "@vonage/vonage-mcp-server-api-bindings"
    ],
    "env": {
        "VONAGE_APPLICATION_ID": "<YOUR_VONAGE_APPLICATION_ID>",
        "VONAGE_PRIVATE_KEY64": "<YOUR_VONAGE_PRIVATE_KEY64>",
        "VONAGE_API_KEY": "<YOUR_VONAGE_API_KEY>",
        "VONAGE_API_SECRET": "<YOUR_VONAGE_API_SECRET>",
        "VONAGE_VIRTUAL_NUMBER": "<YOUR_VONAGE_VIRTUAL_NUMBER>",
        "VONAGE_WHATSAPP_NUMBER": "<YOUR_VONAGE_WHATSAPP_NUMBER>",
        "RCS_SENDER_ID": "<YOUR_RCS_SENDER_ID>"
    }
}

编码你的私钥

VONAGE_PRIVATE_KEY64 必须是你的应用程序私钥文件经过 Base64 编码后形成的单行内容。 在本地运行以下命令之一，将 private.key 替换为密钥文件的路径，然后将输出粘贴到配置中：

macOS：

base64 -i private.key

Linux：

base64 -w 0 private.key

Windows PowerShell：

[Convert]::ToBase64String([IO.File]::ReadAllBytes((Resolve-Path .\private.key)))

安全性

STDIO 传输

此服务在本地运行，并通过 STDIO 与 MCP 客户端（VS Code、Cursor、Claude Desktop 等）通信。工具调用及其响应以明文 JSON-RPC 的形式在两个进程间传输。此通道没有传输层加密或身份验证；本地 MCP 服务的设计方式就是如此。

在你信任的单用户设备上，这种方式是安全的，也是运行此服务的预期方式。请注意：

• 同一设备上拥有足够权限的任何进程都能读取或篡改 STDIO 流。如果设备遭到入侵，服务无法保护通过该通道传输的数据。
• 在共享、多用户或容器化环境中，其他用户或工作负载可能会观察到该进程。只有在信任同时运行的所有其他程序时，才运行此服务。

存储凭据

上述设置会将你的 Vonage 凭据（包括 VONAGE_PRIVATE_KEY64）以明文形式写入 MCP 客户端的配置文件（例如 claude_desktop_config.json 或 .cursor/mcp.json）。以你的用户身份运行的任何进程都能读取该文件，而且很容易意外泄露。

• 将 VONAGE_PRIVATE_KEY64 视同 SSH 私钥。任何拥有它的人都能以你的 Vonage 应用程序身份执行操作。
• 如果配置文件位于项目中，例如 .cursor/mcp.json 或 .vscode/mcp.json，请将其添加到该项目的 .gitignore 中，以免提交。
• 云同步服务（iCloud、Dropbox、OneDrive、Google Drive）可能会在不提示的情况下上传配置目录。请将这些目录排除在同步范围之外，或将包含凭据的配置文件放在不同步的文件夹中。
• 如需更强的保护，请勿将密钥存入配置文件。可选方案如下。

不将密钥存入配置文件

此服务只从其环境中读取凭据，因此目标是在启动时让 MCP 客户端提供 VONAGE_PRIVATE_KEY64 和 VONAGE_API_SECRET，而不将它们写入文件。这样可以保护静态存储的凭据。服务运行后，它们仍会存在于其环境中。

macOS（钥匙串）

将密钥存储在登录钥匙串中。私钥太长，无法粘贴到终端提示符中，因此第一条命令会直接从密钥文件读取。第二条命令以 -w 结尾，这会让 security 提示输入 API 密钥，避免其出现在 shell 历史记录中：

security add-generic-password -a "$USER" -s vonage-mcp-private-key64 -w "$(base64 -i private.key)"
security add-generic-password -a "$USER" -s vonage-mcp-api-secret -w

然后通过一个从钥匙串读取密钥的 shell 启动服务，并且只在 env 中保留非机密值：

"vonage-mcp-server-api-bindings": {
    "type": "stdio",
    "command": "/bin/sh",
    "args": [
        "-c",
        "VONAGE_PRIVATE_KEY64=$(security find-generic-password -s vonage-mcp-private-key64 -w) || exit 1; VONAGE_API_SECRET=$(security find-generic-password -s vonage-mcp-api-secret -w) || exit 1; export VONAGE_PRIVATE_KEY64 VONAGE_API_SECRET; exec npx -y @vonage/vonage-mcp-server-api-bindings"
    ],
    "env": {
        "VONAGE_APPLICATION_ID": "<YOUR_VONAGE_APPLICATION_ID>",
        "VONAGE_API_KEY": "<YOUR_VONAGE_API_KEY>",
        "VONAGE_VIRTUAL_NUMBER": "<YOUR_VONAGE_VIRTUAL_NUMBER>",
        "VONAGE_WHATSAPP_NUMBER": "<YOUR_VONAGE_WHATSAPP_NUMBER>",
        "RCS_SENDER_ID": "<YOUR_RCS_SENDER_ID>"
    }
}

服务首次启动时，macOS 可能会询问是否允许 security 访问这些项目。选择 始终允许，这样之后启动时就不会再出现提示。

VS Code（输入变量）

VS Code 可以在服务首次启动时提示输入密钥并安全存储。你可以在 .vscode/mcp.json 或用户配置文件中的 mcp.json 里使用输入变量：

{
  "inputs": [
    {
      "type": "promptString",
      "id": "vonage-private-key64",
      "description": "Vonage private key (base64)",
      "password": true
    },
    {
      "type": "promptString",
      "id": "vonage-api-secret",
      "description": "Vonage API secret",
      "password": true
    }
  ],
  "servers": {
    "vonage-mcp-server-api-bindings": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@vonage/vonage-mcp-server-api-bindings"],
      "env": {
        "VONAGE_APPLICATION_ID": "<YOUR_VONAGE_APPLICATION_ID>",
        "VONAGE_API_KEY": "<YOUR_VONAGE_API_KEY>",
        "VONAGE_PRIVATE_KEY64": "${input:vonage-private-key64}",
        "VONAGE_API_SECRET": "${input:vonage-api-secret}"
      }
    }
  }
}

根据需要，将设置示例中的其余非机密变量添加到 env 中。VS Code 不会将使用输入变量的服务转发到 Copilot harness 会话。详情请参阅 VS Code MCP 配置参考。

Linux 和 Windows

这两个系统都没有默认安装且可正常使用的命令行密钥存储工具。如果你已经在使用此类工具，例如 GNOME Keyring 的 secret-tool 或 PowerShell SecretManagement，可以采用与 macOS 示例相同的模式：通过一个读取密钥并在启动服务前导出密钥的 shell 来启动服务。否则，请遵循上述文件处理建议。