platfone

Platfone MCP 服务

Platfone 提供用于账户验证、测试和自动化工作流的虚拟电话号码。Platfone MCP 服务让 AI Agent 能够通过 Claude、VS Code Copilot、Codex 等兼容 MCP 的客户端获取临时号码并接收短信。

📖 文档 · 🔧 设置指南 · 🔑 获取 API 密钥 · 📦 npm

为什么使用 MCP？

无需手动集成 API，AI Agent 即可：

• 按国家和服务名称自主订购号码
• 等待接收短信验证码
• 重试或取消激活

全部通过结构化工具调用完成，无需自定义后端。

功能

• 完整的激活生命周期 — 从订购号码到接收短信
• ETag 缓存目录 — 国家和服务目录会缓存在内存中，TTL 为 5 分钟，并基于 ETag 进行条件刷新 — 不会发送给 Agent
• 便于理解的输入 — 可使用“Israel”或“Telegram”等名称代替 ID；服务端会自动解析名称
• 双传输方式 — 通过同一代码库支持 stdio 和 http
• API 密钥身份验证 — 可使用现有的 Platfone API 密钥

安装

请参阅完整的安装指南，了解详细说明。

快速开始

NPM：

PLATFONE_API_KEY=your_key npx @platfone/mcp

Agent 指南

• 始终先调用 check_price，以确认价格和可用性
• 然后调用 order_number 租用号码
• 调用 check_sms，直到收到短信或激活过期
• 如果没有收到短信，使用 retry_activation
• 如果不再需要，使用 cancel_activation 释放资金

工具

工具	说明
get_balance	查看账户余额：总额、预留金额和可用资金。
check_price	订购前查看国家与服务组合的价格和可用性。
order_number	订购虚拟电话号码。可接受名称（“Israel”）或 ID（“il”）。返回 activation_id + phone。
check_sms	轮询激活状态。收到短信时返回验证码，否则返回当前状态和轮询说明。
retry_activation	在同一号码上请求另一条短信。免费。
cancel_activation	在收到短信前取消激活。退还预留金额。

注意： 国家和服务目录会缓存在服务端，并根据人类可读的名称自动解析。 Agent 不会收到完整目录，只会收到已解析的 ID 或消除歧义的提示。

典型的 AI Agent 工作流

1. check_price         (country: "Israel", service: "Telegram")  → verify cost & availability
2. order_number        (country: "Israel", service: "Telegram")  → returns activation_id + phone
3. check_sms           (activation_id)                            → poll or check once for SMS

可选步骤：

• retry_activation — 在同一号码上请求另一条短信（免费）
• cancel_activation — 在收到短信前取消（退还余额）

开发

请阅读完整的开发指南，了解设置说明和测试建议。

故障排除

错误	解决方案
UnauthorizedException	检查你的 PLATFONE_API_KEY 是否有效
PaymentRequiredException	为你的 Platfone 余额充值
NoNumbersAvailableException	尝试其他国家或服务
TooManyRequestsException	请求受限 — 等待后重试
MaxPriceExceededException	使用建议的 max_price 和返回的 order_id 重试 order_number
TooManyActivationsException	已达到并发活动激活次数上限 — 取消或等待过期

许可证

请参阅 LICENSE.md。采用 MIT License 授权。

使用 Platfone API 须遵守服务条款和隐私政策。