English Français العربية

io.github.platfone-com/platfone

السجل الرسمي الذكاء الاصطناعي والوكلاء

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

الشيفرة المصدرية التوثيق

ماذا يمكنك أن تفعل مع io.github.platfone-com/platfone؟

  • 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

التثبيت

أضف هذا إلى إعدادات MCP في عميلك (Claude Desktop: claude_desktop_config.json، وCursor: ‏.cursor/mcp.json، ويستخدم VS Code وغيره الصيغة نفسها «mcpServers»).

Remote (streamable-http)
Claude Code 
claude mcp add --transport http platfone 'https://mcp.platfone.com/mcp'
إعداد JSON (Claude Desktop وCursor وVS Code) 
{
    "mcpServers": {
        "platfone": {
            "type": "http",
            "url": "https://mcp.platfone.com/mcp"
        }
    }
}
NPM package @platfone/mcp
Claude Code 
claude mcp add platfone -e 'PLATFONE_API_KEY=<your platfone_api_key>' -- npx -y @platfone/mcp@1.1.8
إعداد JSON (Claude Desktop وCursor وVS Code) 
{
    "mcpServers": {
        "platfone": {
            "command": "npx",
            "args": [
                "-y",
                "@platfone/mcp@1.1.8"
            ],
            "env": {
                "PLATFONE_API_KEY": "<your platfone_api_key>"
            }
        }
    }
}

متغيرات البيئة

  • PLATFONE_API_KEY إلزامي سري Your Platfone API key from https://platfone.com/app/api

التوثيق

مأخوذ من ملف README للمشروع على GitHub ويُحدَّث أسبوعيًا. تفتح الروابط على GitHub.

المحتويات
  1. Platfone MCP Server
  2. Why MCP?
  3. Features
  4. Installation
  5. Agent Guidelines
  6. Tools
  7. Development
  8. Troubleshooting
  9. License

Platfone 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 — 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:

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

ToolDescription
get_balanceCheck account balance: total, reserved, and available funds.
check_priceCheck pricing and availability for a country + service pair before ordering.
order_numberOrder a virtual phone number. Accepts names ("Israel") or IDs ("il"). Returns activation_id + phone.
check_smsPoll activation state. Returns SMS code when received, or current status with polling instructions.
retry_activationRequest another SMS on the same number. Free of charge.
cancel_activationCancel 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

ErrorSolution
UnauthorizedExceptionCheck your PLATFONE_API_KEY is valid
PaymentRequiredExceptionTop up your Platfone balance
NoNumbersAvailableExceptionTry a different country or service
TooManyRequestsExceptionRate limited — wait and retry
MaxPriceExceededExceptionRetry order_number with the suggested max_price and returned order_id
TooManyActivationsExceptionMax 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.

الأسئلة الشائعة

ما هو io.github.platfone-com/platfone؟

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

كيف أثبّت io.github.platfone-com/platfone؟

يعمل كخادم بعيد. في Claude Code: claude mcp add --transport http platfone 'https://mcp.platfone.com/mcp'. وفي العملاء الآخرين، الصق إعداد JSON من هذه الصفحة في إعدادات MCP الخاصة بهم.

هل يحتاج io.github.platfone-com/platfone إلى مفتاح API؟

نعم. يتطلب PLATFONE_API_KEY، وتضبطها في إعداداته.

هل io.github.platfone-com/platfone مفتوح المصدر؟

نعم. شيفرته متاحة على GitHub بترخيص MIT.

من يصون io.github.platfone-com/platfone؟

ينشره platfone-com. يدرجه AI.tn لكنه لا يصونه ولا يوصي به.

من سجل MCP الرسمي. الإدراج ليس توصية: راجع شيفرة الخادم وصلاحياته قبل منحه الوصول إلى بياناتك.