Skip to main content
Glama
TopSMS MCP server

TopSMS MCP server

TopSMS MCP server

Send SMS from Claude, ChatGPT, Cursor and other AI assistants through TopSMS (topsms.eu / topsms.cz), an SMS gateway for businesses with two sites:

  • topsms.eu – English, German, Italian, Spanish and Portuguese; accounts in EUR; for Germany, Austria and the EU.

  • www.topsms.cz – Czech and Slovak; accounts in CZK.

Both sites share one API: REST API, Verify (OTP) API, webhooks with delivery reports, and test API keys that send nothing and cost nothing. Prepaid credit, no monthly fee, no setup fee, credit never expires.

There are two ways to connect:

  • Remote MCP server https://topsms.eu/api/mcp – nothing to install; sign in with OAuth or send an API key in the Authorization header.

  • This npm package topsms-mcp – a local stdio server for clients that start MCP servers as a command.

Tools

Tool

What it does

send_sms

Send one SMS (number, text, optional sender name, optional send_at to schedule, optional idempotency key)

send_bulk_sms

Same text to up to 500 numbers; over 50 recipients it is queued and returns a jobId

get_message_status

Delivery status of a message (queued, sent, delivered, failed, expired)

get_bulk_job

Progress of a queued or scheduled send

cancel_scheduled

Cancel a scheduled send (the price is returned to credit)

verify_send

Send a one-time verification code (OTP) by SMS

verify_check

Check the code the user entered

get_credit

Credit balance and price per SMS in the account currency (EUR or CZK)

get_pricing

Public price list (no credentials needed)

Related MCP server: SMS Masivos MCP Server

Quick start

  1. Create an account at topsms.eu (EUR account, €0.50 sign-up credit, about 5 SMS) or www.topsms.cz (CZK account, 10 test SMS).

  2. Connect your AI client, either to the remote server (option A) or with the npm package (option B).

For development, create a test API key in the dashboard: every tool works, but nothing is sent and nothing is charged.

Option A: remote server (OAuth, nothing to install)

Endpoint: https://topsms.eu/api/mcp (Streamable HTTP). Accounts created on www.topsms.cz may also use https://www.topsms.cz/api/mcp.

  • Claude (claude.ai, desktop and mobile apps): Settings → Connectors → Add custom connector, URL https://topsms.eu/api/mcp, leave the OAuth client ID and secret empty, Connect, sign in to TopSMS and allow access. Custom connectors depend on your Claude plan and organisation settings.

  • ChatGPT: Settings → Apps & Connectors, enable Developer mode (advanced settings, available on some plans), create a connector with the URL https://topsms.eu/api/mcp and OAuth authentication, sign in to TopSMS and allow access.

  • Claude Code: claude mcp add --transport http topsms https://topsms.eu/api/mcp, then run /mcp and sign in in the browser.

  • Cursor and other clients without OAuth: send an API key in the header Authorization: Bearer CLIENT_ID:SECRET:

{
  "mcpServers": {
    "topsms": {
      "url": "https://topsms.eu/api/mcp",
      "headers": { "Authorization": "Bearer CLIENT_ID:SECRET" }
    }
  }
}

Each OAuth connection appears in the TopSMS dashboard as an API key named "OAuth: "; revoke it there to disconnect.

Option B: npm package (stdio)

In the dashboard open API keys (API klíče on topsms.cz), create a key with the scopes send and read, and copy the Client ID and Secret. Requires Node.js 18 or newer.

Claude Desktop, Cursor, Windsurf, VS Code and other stdio clients:

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

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

The API key decides the account and its currency; the same package works for topsms.eu and topsms.cz accounts. Optional: TOPSMS_BASE_URL (default https://www.topsms.cz); set it to https://topsms.eu if you want get_pricing to return the EUR price list instead of the CZK one.

Pricing

Prices as of 17 November 2026. All prices are final; no VAT is added.

  • EUR accounts (topsms.eu): €0.089 per SMS segment to Germany, Austria and most EU countries (EU zone). Czech and Slovak numbers: €0.038–0.041 by monthly volume.

  • CZK accounts (www.topsms.cz): 0,99 Kč per SMS to Czech and Slovak numbers; 0,96 Kč from 5 000 Kč monthly spend; 0,93 Kč from 15 000 Kč.

  • No monthly fee, no setup fee. Credit never expires; unused credit is not refunded.

  • Own alphanumeric sender name: on topsms.eu no fee for most EU countries (country rules apply, for example Austria's RTR register, Spain's CNMC registry, Italy's AGCOM registration for Italian VAT holders; France may require registration). On CZK accounts 500 Kč one-off for Czech and Slovak operators, no monthly fee.

Current prices: https://topsms.eu/pricing (EUR) · https://www.topsms.cz/cenik (CZK) · machine-readable https://topsms.eu/pricing.json · per country https://topsms.eu/countries. The get_pricing tool returns the current price list, so an assistant does not need to rely on this README.

Notes

License

MIT

Available Tools

9 tools
cancel_scheduledAInspect

Cancel a scheduled send (or a queued bulk job that has not started yet). Unsent messages are removed and their price is returned to credit.

Inputs: jobId (required).

get_bulk_jobAInspect

Get progress of a queued bulk send (status, sent, failed, queued counts and per-message results).

Inputs: jobId (required), results.

get_creditAInspect

Get the current TopSMS credit balance and the price per SMS, both in your account currency (field currency: EUR for topsms.eu accounts, CZK for topsms.cz accounts).

Inputs: no named parameters.

get_message_statusAInspect

Get delivery status of a sent message (queued, sent, delivered, failed, expired) with timestamps, errorMessage and machine-readable errorCode (expired, undelivered, rejected, deleted, unknown, repeated_failure, not_sent), by message id or external id.

Inputs: id (required).

get_pricingAInspect

Get the current public TopSMS price list (prices per destination zone, volume tiers, sender name fee, billing rules). Does not require credentials. Use it instead of quoting prices from memory.

Inputs: no named parameters.

send_bulk_smsAInspect

Send the same SMS text to up to 500 recipients. Batches over 50 recipients are queued (HTTP 202) and return a jobId; use get_bulk_job to follow progress.

Inputs: to (required), text (required), from, send_at, +1 more.

send_smsAInspect

Send one SMS message via the TopSMS SMS gateway (topsms.eu / topsms.cz). Costs credit: 160 GSM-7 chars = 1 SMS, 70 with other diacritics/emoji. Returns message id, number of segments and price in your account currency (field currency: EUR for topsms.eu accounts, CZK for topsms.cz).

Inputs: to (required), text (required), from, send_at, +1 more.

verify_checkAInspect

Check a verification code the user entered. Returns valid true/false, status (approved, pending, expired, failed, canceled) and attempts left (max 5 attempts per code).

Inputs: code (required), id, to.

verify_sendAInspect

Send a one-time verification code (OTP) by SMS for login, registration or payment confirmation. TopSMS generates and stores the code; returns a verification id. Limits: 5 codes per number per hour, 30 s between codes.

Inputs: to (required), ttl, from, brand, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 9 tools

    Disambiguation5/5

    Each tool targets a distinct resource+action pair: single send vs bulk send, single message status vs bulk job progress, verify_send vs verify_check, and balance vs price list. The only near-neighbours (get_credit / get_pricing) are explicitly differentiated in their descriptions as balance vs public price list. No two tools appear interchangeable.

    Naming Consistency4/5

    All names are snake_case and verb-first, with a clear verb+object shape (send_sms, get_message_status, get_bulk_job, get_credit). Minor deviations exist: cancel_scheduled has an adjectival object with no resource noun, and verify_send/verify_check use a verb+verb form rather than verb+noun. Still highly predictable overall.

    Tool Count5/5

    Nine tools is well-scoped for an SMS gateway: sending (single/bulk), tracking (single/bulk), cancellation, OTP verification, and account lookup. Each tool covers a distinct capability with no filler or redundant wrappers.

    Completeness3/5

    The core send/track/verify/credit surface is covered, but cancel_scheduled is orphaned — there is no tool to schedule a send or bulk job in the first place, so that capability is a dead end. Other notable gaps: no tool to list message history or inbound/received messages, and sender-name configuration is only mentioned in pricing.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Enables AI assistants and MCP-compatible clients to send and manage SMS messages through the 46elks API, leveraging Swedish telecommunications infrastructure.
      6
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to send SMS, manage contacts, verify numbers, and query campaigns via SMS Masivos platform using natural language.
      30
      57 npm
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Connects any MCP-compatible AI assistant to the MojaWave SMS Gateway, enabling sending SMS, checking credit balances, and managing bulk SMS jobs.
      10
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables sending SMS messages, managing contacts, campaigns, and inbox from AI assistants like Claude and ClickUp.
      33 npm
      MIT