joltsms-sms

@joltsms/mcp-server

JoltSMS 的 MCP 服务——为 AI Agent 提供专用真实 SIM 卡美国电话号码，并接收 SMS/OTP 验证码。

该服务基于 Model Context Protocol，让 AI Agent（Claude Code、Claude Desktop、Cursor 等）能够通过标准化工具调用租用电话号码、等待接收 SMS、提取 OTP 验证码并管理账单。

快速开始

1. 获取 API 密钥

创建 JoltSMS 账户，并在 Dashboard → Settings → API Keys 中生成 API 密钥。

2. 配置 MCP 客户端

添加到 .mcp.json（Claude Code）或 MCP 设置（Claude Desktop、Cursor）中：

{
  "mcpServers": {
    "joltsms": {
      "command": "npx",
      "args": ["-y", "@joltsms/mcp-server@2"],
      "env": {
        "JOLTSMS_API_KEY": "jolt_sk_your_key_here"
      }
    }
  }
}

3. 开始使用

现在，你的 AI Agent 可以使用全部 12 个 JoltSMS 工具。试试这样说：

“列出我保存的银行卡，然后使用我选择的银行卡租用下一个可用号码。”

工具

工具	说明
joltsms_list_numbers	列出有效号码及其服务标签、标签和未读数量
joltsms_get_number	查看单个号码的完整详情
joltsms_update_number	为号码设置服务标签、标签或备注
joltsms_list_payment_methods	列出已保存的掩码银行卡和支付方式 ID
joltsms_provision_number	租用下一个可用号码，可选择使用已保存的银行卡（月费 50 美元）
joltsms_release_number	在周期结束时停止自动续费，或取消尚未付款的首次结账
joltsms_list_messages	列出近期 SMS，并显示已解析的 OTP 验证码和消息 ID
joltsms_reply_to_sms	回复符合条件的入站消息（最多 15 个字符）
joltsms_mark_read	将单条或多条消息标记为已读
joltsms_wait_for_sms	轮询，直到收到 SMS（OTP 工作流的关键工具）
joltsms_get_latest_otp	获取最近解析出的验证码
joltsms_billing_status	检查最多 10 个订阅的账单状态

工具注解（2.0.2）

全部 12 个工具通过 tools/list 提供人类可读的 annotations.title，以及明确的布尔值 readOnlyHint、destructiveHint、idempotentHint 和 openWorldHint。

工具	只读	有破坏性	幂等	开放世界
列出号码、获取号码、列出支付方式、列出消息、等待 SMS、获取最新 OTP、账单状态	true	false	true	false
更新号码元数据	false	true	true	false
租用号码、释放号码、回复 SMS	false	true	false	true
标记消息为已读	false	false	true	false

“有破坏性”包括覆盖标签/备注、支付费用、取消服务，以及发送无法撤回的 SMS。账户读取和已读状态更新仅在你的 JoltSMS 私人账户内进行。租用、取消和回复会与账户以外的支付或电信服务交互。

租用操作会保护待处理的尝试，但成功后再次调用可能会购买另一个号码。每次回复调用都会使用新的请求密钥。每次取消调用都会发送新的 API 请求，且不保证自动重试安全。 这些提示有助于客户端准确呈现操作；执行授权操作仍需具备 API 权限并获得用户批准。

2.0.2 版本还将捆绑的 ip-address 更新至 10.7.4，以修复 GHSA-rxp7-6hxx-x8q5。

OTP 验证工作流

最常见的用例——自动化手机验证：

1. joltsms_provision_number({ payment_method_id: "pm_chosen_from_saved_cards" })
   → Number provisioning started! Use joltsms_list_numbers to check when it is ACTIVE.

2. joltsms_list_numbers({})
   → Once provisioning completes: +17245550100 (ACTIVE)

3. joltsms_update_number({ number_id: "+17245550100", service_name: "PayPal" })
   → Tagged for easy lookup later

4. [Agent enters phone number on PayPal and requests OTP]

5. joltsms_wait_for_sms({ number_id: "+17245550100", timeout_seconds: 120 })
   → SMS received after 8.2s: "Your PayPal code is 847291"
   → OTP Code: 847291

6. joltsms_mark_read({ number_id: "+17245550100" })
   → Inbox clean

7. [Agent enters 847291 on PayPal — verification complete]

环境变量

变量	必需	说明
JOLTSMS_API_KEY	是	你的 API 密钥（jolt_sk_*）
JOLTSMS_API_URL	否	API 基础 URL（默认为 https://api.joltsms.com）

要求

• 已安装安全补丁的 Node.js 版本：22.x 中的 22.23.4+、24.x 中的 24.22.1+， 或 26.x 中的 26.12.1+
• 拥有 JoltSMS 账户，且已绑定付款方式
• 如果需要进行付款身份验证，请打开工具返回的托管发票 URL
• 短信回复需要具备短信回复功能的 API 密钥

Node.js 安全更新（2.0.1）

2.0.1 版本要求安装 2026 年 10 月 21 日发布的 Node.js 安全补丁。 启动时会检查 Node 运行时；如果补丁版本过旧、主版本不受支持或使用的是预发布版本，则会退出并提示升级。仅依靠 npm 的引擎警告无法强制执行此要求。

对于通过 npx 安装的情况，请在启动 MCP 客户端的机器上更新 Node，在该环境中检查 node --version，然后重启 MCP 连接。客户端使用的 PATH 可能与终端不同；请确保客户端环境也选择了已安装补丁的 Node 二进制文件。安装新的 npm 包不会替换 Node 本身。Docker 构建在两个阶段都使用 node:22.23.4-slim；请重新构建并替换现有容器，以使用已安装补丁的运行时。

API 密钥、可执行文件名称和全部 12 个工具均未更改。

从 1.x 升级

请使用上述任一已安装补丁的 Node.js 版本，将 MCP 配置中固定的版本改为 @joltsms/mcp-server@2，然后重启 MCP 连接。现有 JoltSMS API 密钥以及 mcp-server / joltsms-mcp 可执行文件名称仍可使用。

无法选择区号。请移除旧的 area_code 参数：租用时会使用下一个可用的美国专用手机号码。每次配置调用会订购一个号码；分组结账仍可在控制面板中进行。

如需选择已保存的银行卡，请调用 joltsms_list_payment_methods，让用户选择一张，然后将其 payment_method_id 传递给 joltsms_provision_number。省略该参数时，会使用有效的账户默认卡，或唯一一张已保存的卡。如果需要身份验证，工具会返回托管发票 URL 和待处理的订阅 ID。未付款且已放弃的结账可以通过 joltsms_release_number 取消；已付款的租赁会继续提供服务，直到客户的计费周期结束。

号码详情会分别显示客户服务有效期和下次扣费／重试日期。服务提供商的租赁到期日并不代表客户服务结束日期。号码列表和账单摘要最多显示 10 条记录；账户号码较多时，请使用 joltsms_get_number 查询特定号码，或通过控制面板查看完整列表。

回复针对现有的入站消息 ID。它们不接受任意目标号码，也不会启用外发营销活动。

开发

npm ci --ignore-scripts
npm test
npm run test:package
npm audit --audit-level=low

有关源代码同步、兼容性检查，以及 npm 和 MCP Registry 各自的发布步骤，请参阅 RELEASING.md。

文档

• MCP 服务文档
• API 参考
• JoltSMS 网站

许可证

MIT