MCP server

SMS from AI assistants

The Model Context Protocol (MCP) is the standard through which AI assistants call tools. With the official TopSMS MCP server you tell Claude, Cursor or another assistant “text the customer that the order is on its way” and it does so through your TopSMS account, checking delivery status and credit along the way.

What it can do

• send_sms: sends an SMS to one number, optionally with your approved sender, immediately or scheduled (send_at)
• send_bulk_sms: the same text to up to 500 numbers, large batches are queued
• get_message_status and get_bulk_job: delivery status of a message (including the non-delivery reason errorCode) and the progress of a batch
• cancel_scheduled: cancels a scheduled send and refunds the credit
• verify_send and verify_check: sends a verification code (OTP) and checks it, see the Verify API
• get_credit: credit balance and price per SMS
• get_pricing: public price list (no login required)

The server calls the same REST API as your application, so the same prices, limits and billing rules apply. The sending tools accept an optional idempotencyKey: when the assistant repeats a call, the SMS is not sent twice. Package: npmjs.com/package/topsms-mcp.

Installing in Claude Desktop, Cursor and others

In the dashboard, under API keys, create a key with the scopes send and read and add this to your MCP client configuration:

{
  "mcpServers": {
    "topsms": {
      "command": "npx",
      "args": ["-y", "topsms-mcp"],
      "env": {
        "TOPSMS_CLIENT_ID": "your-client-id",
        "TOPSMS_SECRET": "your-secret"
      }
    }
  }
}

Claude Code with a single command:

claude mcp add topsms -e TOPSMS_CLIENT_ID=... -e TOPSMS_SECRET=... -- npx -y topsms-mcp

You need Node.js 18 or newer. Cursor, Windsurf and VS Code use the same configuration format.

Security and costs

• Every send uses real credit. Keep tool-call confirmation enabled in your client, so the assistant asks before sending.
• Create a separate API key for the AI assistant. In the dashboard you see its usage separately and can revoke it at any time.
• The key stays on your computer in the client configuration; the server sends it only to www.topsms.cz.
• For recurring automations that need no AI, Make or the REST API is the better fit.

Get an API key →

Related