io.github.platfone-com/platfone
Virtual phone numbers for AI agents — rent numbers in 200+ countries, receive SMS.
Open source Repository Open in the app JSON README (API)
About
Virtual phone numbers for AI agents — rent numbers in 200+ countries, receive SMS.
Details
- Kind
- MCP servers
- Topic
- Communication
- Publisher
- platfone-com
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 1.1.8
- Stars
- 4
- Forks
- 1
- Open pull requests
- 1
- Last push
- 2026-05-05T16:00:16Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 04:01:12
- Updated
- 2026-08-29 04:01:12
- Origin id
io.github.platfone-com/platfone
README
# Platfone MCP Server
[](https://www.npmjs.com/package/@platfone/mcp)
[](https://www.npmjs.com/package/@platfone/mcp)
[](https://opensource.org/licenses/MIT)
[](https://smithery.ai/server/dima-p0g6/platfone)
[Platfone](https://platfone.com) 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](https://platfone.com/docs/mcp/) · 🔧 [Setup Guide](https://platfone.com/docs/mcp/setup/) · 🔑 [Get API Key](https://platfone.com/app/api) · 📦 [npm](https://www.npmjs.com/package/@platfone/mcp)
## 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](https://platfone.com/docs/mcp/setup) 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
```
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](docs/DEVELOPMENT.md) 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](./LICENSE.md). Licensed under the MIT License.
Use of the Platfone API is subject to [Terms of Service](https://platfone.com/compliance#terms) and [Privacy Policy](https://platfone.com/compliance#privacy).