Allows AI agents to rent virtual phone numbers in over 200 countries and receive SMS messages for account verification and automation.
Also known as platfone-com/mcp, mcp, @platfone/mcp
- Stars
- 4
- Tools
- 6
- Downloads, 30 days
- โ
- Latest version
- 1.1.8
- Last commit
- Oct 23, 2026
- License
- MIT
What is Platfone MCP?
Platfone allows AI agents to rent virtual phone numbers in over 200 countries and receive SMS messages for account verification and automation. It exposes 6 tools, such as get_balance, check_price, order_number.
Summary generated from the project's README
About Platfone MCP server
Platfone provides a way for AI agents to manage virtual phone numbers across more than 200 countries. This MCP server allows clients like Claude or VS Code Copilot to automate account verification and testing workflows by renting numbers and receiving SMS messages directly through tool calls. It functions via stdio or http transport and requires a Platfone API key for authentication.
Developers can use specific tools to handle the entire activation lifecycle. The server includes functions to check account balances, verify pricing for specific country and service combinations, and order numbers using human-readable names like Israel or Telegram. It also manages the retrieval of SMS codes and provides options to retry an activation or cancel an order to refund the reserved balance. To maintain efficiency, the server uses an ETag-cached catalog that resolves names to IDs server-side so the agent does not have to process large datasets.
What you can do with it
- 1Cost and availability checkingA developer can instruct an agent to verify if a specific country and service are affordable before proceeding.
- 2Managing activation failuresThe agent can request a new SMS code if the first one does not arrive.
- 3Resource and fund managementAn agent can release funds by canceling an activation that is no longer needed.
Written from the project's README. Every use case is checked against a quote from it.
How to install Platfone MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Platfone MCP in Claude Code
$ claude mcp add --env 'PLATFONE_API_KEY=<YOUR_PLATFONE_API_KEY>' mcp -- npx -y @platfone/mcpInstall Platfone MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@platfone/mcp"
],
"env": {
"PLATFONE_API_KEY": "<YOUR_PLATFONE_API_KEY>"
}
}
}
}Install Platfone MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@platfone/mcp"
],
"env": {
"PLATFONE_API_KEY": "<YOUR_PLATFONE_API_KEY>"
}
}
}
}Install Platfone MCP in VS Code CLI
$ code --add-mcp '{"name":"mcp","type":"stdio","command":"npx","args":["-y","@platfone/mcp"],"env":{"PLATFONE_API_KEY":"<YOUR_PLATFONE_API_KEY>"}}'Install Platfone MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@platfone/mcp"
],
"env": {
"PLATFONE_API_KEY": "<YOUR_PLATFONE_API_KEY>"
}
}
}
}Install Platfone MCP in Codex
$ codex mcp add mcp --env 'PLATFONE_API_KEY=<YOUR_PLATFONE_API_KEY>' -- npx -y @platfone/mcpInstall Platfone MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp] command = "npx" args = ["-y", "@platfone/mcp"] [mcp_servers.mcp.env] PLATFONE_API_KEY = "<YOUR_PLATFONE_API_KEY>"
Install Platfone MCP in Gemini CLI
$ gemini mcp add -s user -e 'PLATFONE_API_KEY=<YOUR_PLATFONE_API_KEY>' mcp npx -- -y @platfone/mcpInstall Platfone MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@platfone/mcp"
],
"env": {
"PLATFONE_API_KEY": "<YOUR_PLATFONE_API_KEY>"
}
}
}
}Needs a key before it starts
Started on 16 Nov 2026 with no keys, it stopped and asked for one, so a client sees no tools until you set the variables above.
Platfone MCP tools 6
Detected from the READMEget_balancecheck_priceorder_numbercheck_smsretry_activationcancel_activation
Configuration
PLATFONE_API_KEYRequiredSecretYour Platfone API key from https://platfone.com/app/api
Automated checks
Ran Nov 12, 2026Full report โPassed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSPass
- Destructive tools are labelledPass
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubPlatfone MCP Server
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 โ
stdioandhttpfrom 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:
PLATFONE_API_KEY=your_key npx @platfone/mcp
Agent Guidelines
- Always call
check_pricefirst to verify cost and availability - Then call
order_numberto rent a number - Call
check_smsuntil SMS is received or expired - Use
retry_activationif no SMS arrives - Use
cancel_activationto 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 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.
Platfone MCP questions
How do I add Platfone MCP to Claude Code?
Run claude mcp add --env 'PLATFONE_API_KEY=<YOUR_PLATFONE_API_KEY>' mcp -- npx -y @platfone/mcp in your terminal. Add --scope user to make it available in every project.
How do I add Platfone MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Platfone MCP provide?
It exposes 6 tools, including get_balance, check_price, order_number, check_sms, retry_activation.
How can I verify the cost of a number before ordering?
You should call the check_price tool first to verify the cost and availability for a specific country and service pair.
How do I authenticate with the server?
The server uses an API key for authentication, which can be provided via the PLATFONE_API_KEY environment variable.