@joltsms/mcp-server

MCP server for JoltSMS — provision dedicated real-SIM US phone numbers and receive SMS/OTP codes through AI agents.

Built on the Model Context Protocol, this server gives AI agents (Claude Code, Claude Desktop, Cursor, etc.) the ability to rent phone numbers, wait for incoming SMS, extract OTP codes, and manage billing — all through standardized tool calls.

Quick Start

1. Get an API Key

Create a JoltSMS account and generate an API key at Dashboard → Settings → API Keys.

2. Configure Your MCP Client

Add to your .mcp.json (Claude Code) or MCP settings (Claude Desktop, Cursor):

{
  "mcpServers": {
    "joltsms": {
      "command": "npx",
      "args": ["-y", "@joltsms/mcp-server@2"],
      "env": {
        "JOLTSMS_API_KEY": "jolt_sk_your_key_here"
      }
    }
  }
}

3. Use It

Your AI agent now has access to all 12 JoltSMS tools. Try:

"List my saved cards, then rent the next available number using the card I choose."

Related MCP server: @saperly/mcp

Tools

Tool annotations (2.0.2)

All 12 tools expose a human-readable annotations.title and explicit boolean readOnlyHint, destructiveHint, idempotentHint, and openWorldHint values through tools/list.

“Destructive” includes overwriting labels/tags/notes, spending money, canceling service, and sending an SMS that cannot be recalled. Account reads and read-status updates stay within your private JoltSMS account. Rentals, cancellations, and replies interact with payment or telecom services outside it.

Provisioning protects a pending attempt, but a new call after success can buy another number. Replies use a new request key per call. Cancellation sends a new API request on each call and does not promise safe automatic retries. These hints help clients present actions accurately; API permissions and user approval are still required for authorized actions.

Version 2.0.2 also updates bundled ip-address to 10.7.4 for GHSA-rxp7-6hxx-x8q5.

OTP Verification Workflow

The most common use case — automated phone verification:

1. joltsms_provision_number({ payment_method_id: "pm_chosen_from_saved_cards" })
   → Number provisioning started! Use joltsms_list_numbers to check when it is ACTIVE.

2. joltsms_list_numbers({})
   → Once provisioning completes: +17245550100 (ACTIVE)

3. joltsms_update_number({ number_id: "+17245550100", service_name: "PayPal" })
   → Tagged for easy lookup later

4. [Agent enters phone number on PayPal and requests OTP]

5. joltsms_wait_for_sms({ number_id: "+17245550100", timeout_seconds: 120 })
   → SMS received after 8.2s: "Your PayPal code is 847291"
   → OTP Code: 847291

6. joltsms_mark_read({ number_id: "+17245550100" })
   → Inbox clean

7. [Agent enters 847291 on PayPal — verification complete]

Environment Variables

Requirements

• A patched Node.js release: 22.23.4+ within 22.x, 24.22.1+ within 24.x, or 26.12.1+ within 26.x

• A JoltSMS account with a payment method on file

• If payment authentication is required, open the hosted invoice URL returned by the tool

• SMS replies require an API key with the SMS replies capability

Node.js security update (2.0.1)

Version 2.0.1 requires the October 21, 2026 Node.js security patches. It checks the Node runtime at startup and exits with an upgrade message on an older patch, unsupported major, or prerelease. npm's engine warning alone does not enforce this requirement.

For npx installations, update Node on the machine that launches your MCP client, check node --version in that environment, then restart the MCP connection. Clients can use a different PATH from your terminal; ensure their environment selects the patched Node binary too. Installing a new npm package does not replace Node itself. The Docker build uses node:22.23.4-slim in both stages; rebuild and replace existing containers to use the patched runtime.

The API key, executable names, and all 12 tools are unchanged.

Upgrading from 1.x

Use one of the patched Node.js versions above, change a pinned MCP configuration to @joltsms/mcp-server@2, and restart the MCP connection. Your existing JoltSMS API key and the mcp-server / joltsms-mcp executable names still work.

Area codes are not selectable. Remove the old area_code argument: rentals use the next available dedicated U.S. mobile number. Each provisioning call orders one number; grouped checkout remains in the dashboard.

To choose a saved card, call joltsms_list_payment_methods, let the user select one, and pass its payment_method_id to joltsms_provision_number. Omitting it uses a valid account default or the sole saved card. If authentication is needed, the tool returns a hosted invoice URL and a pending subscription ID. An abandoned unpaid checkout can be canceled with joltsms_release_number; paid rentals retain service until the customer billing period ends.

Number details show customer service-through and next-charge/retry dates separately. Provider rental expiry is not a customer service end date. The number list and billing summary display at most 10 entries; use joltsms_get_number to look up a specific number on larger accounts, or use the dashboard for the full list.

Replies target an existing inbound message ID. They do not accept an arbitrary destination or enable outbound campaigns.

Development

npm ci --ignore-scripts
npm test
npm run test:package
npm audit --audit-level=low

See RELEASING.md for source synchronization, compatibility checks, and the separate npm and MCP Registry publication steps.

Documentation

• MCP Server Docs

• API Reference

• JoltSMS Website

License

MIT