io.github.platfone-com/platfone

OfficialLive

by platfone-com · TypeScript

Virtual phone numbers for AI agents — rent numbers in 200+ countries, receive SMS.

Platfone MCP Server (Model Context Protocol)

The io.github.platfone-com/platfone MCP server provides access to Platfone virtual phone numbers for AI agents. It supports renting numbers in 200+ countries and receiving SMS for uses such as OTP and phone verification, including SMS delivery workflows.

🛠️ Key Features

Virtual phone numbers for account verification
Rent numbers in 200+ countries
Receive SMS (including SMS/OTP verification)

🚀 Use Cases

OTP and SMS verification for automated workflows
Account verification for testing and automation
Phone-number based verification for AI agents

⚡ Developer Benefits

Built as an MCP server aligned to Model Context Protocol
TypeScript-related implementation (topics include TypeScript)
Topic coverage includes MCP server and model-context-protocol integration

⚠️ Limitations

The provided excerpt does not describe specific APIs, authentication, availability by region beyond “200+ countries,” or tool-level details.

Topics

ai-agentclaudecursormcpmcp-servermodel-context-protocolotpphone-verificationreceive-smssmssms-activatesms-verificationtemp-numbertypescriptvirtual-number

README.md5 KBView on GitHub

Platfone MCP Server

Smithery

Platfone provides virtual phone numbers for account verification, testing, and automation workflows. The Platfone MCP server enables AI agents to obtain temporary numbers and receive SMS messages from MCP-compatible clients like Claude, VS Code Copilot, Codex, etc.

📖 Docs · 🔧 Setup Guide · 🔑 Get API Key · 📦 npm

Why MCP?

Instead of manually integrating the API, AI agents can:

Order numbers autonomously by country and service name
Wait for SMS codes
Retry or cancel activations

All via structured tool calls — no custom backend required.

Features

Full activation lifecycle — from ordering a number to receiving SMS
ETag-cached catalog — countries and services are cached in-memory with 5-minute TTL and ETag-based conditional refresh — never sent to the agent
Human-friendly inputs — use "Israel" or "Telegram" instead of IDs; names are auto-resolved server-side
Dual transport — stdio and http from a single codebase
API key auth — works with your existing Platfone API key

Installation

See the full Installation Guide for detailed instructions.

Quick Start

NPM:

bash

PLATFONE_API_KEY=your_key npx @platfone/mcp

Agent Guidelines

Always call check_price first to verify cost and availability
Then call order_number to rent a number
Call check_sms until SMS is received or expired
Use retry_activation if no SMS arrives
Use cancel_activation to release funds if no longer needed

Tools

Tool	Description
`get_balance`	Check account balance: total, reserved, and available funds.
`check_price`	Check pricing and availability for a country + service pair before ordering.
`order_number`	Order a virtual phone number. Accepts names ("Israel") or IDs ("il"). Returns `activation_id` + `phone`.
`check_sms`	Poll activation state. Returns SMS code when received, or current status with polling instructions.
`retry_activation`	Request another SMS on the same number. Free of charge.
`cancel_activation`	Cancel an active activation before SMS is received. Refunds reserved amount.

Note: Country and service catalogs are cached server-side and auto-resolved from human-readable names. The agent never receives the full catalog — only resolved IDs or disambiguation hints.

Typical AI Agent Flow

code

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

Optional steps:

retry_activation — request another SMS on the same number (free)
cancel_activation — cancel before SMS arrives (refunds balance)

Development

Read the full Development Guide for setup instructions and testing tips.

Troubleshooting

Error	Solution
`UnauthorizedException`	Check your `PLATFONE_API_KEY` is valid
`PaymentRequiredException`	Top up your Platfone balance
`NoNumbersAvailableException`	Try a different country or service
`TooManyRequestsException`	Rate limited — wait and retry
`MaxPriceExceededException`	Retry `order_number` with the suggested `max_price` and returned `order_id`
`TooManyActivationsException`	Max concurrent active activations reached — cancel or wait for expiry

License

See LICENSE.md. Licensed under the MIT License.

Use of the Platfone API is subject to Terms of Service and Privacy Policy.

Install

Configuration

Environment variables

PLATFONE_API_KEYrequiredsecret

Your Platfone API key from https://platfone.com/app/api

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "platfone": {
      "command": "npx",
      "args": [
        "-y",
        "@platfone/mcp@1.1.8"
      ],
      "env": {
        "PLATFONE_API_KEY": "<YOUR_PLATFONE_API_KEY>"
      }
    }
  }
}