io.github.rchanllc/joltsms-sms MCP Server

Provision real-SIM US phone numbers, receive SMS, and extract OTP codes for AI agents. This MCP server enables rental of numbers, inbound SMS handling, OTP extraction, and billing management via standardized tool calls, built on the Model Context Protocol.

🛠️ Key Features

Provisions dedicated real-SIM US phone numbers
Receives and processes inbound SMS messages
Extracts OTP codes for AI agents
Billing and account management through MCP tooling
Intended for integration with Claude Code, Claude Desktop, Cursor, and more

🚀 Use Cases

AI agents requiring OTP verification flows
Automated SMS-based authentication for services
Temporary phone-number provisioning for testing and demos
Centralized SMS intake and OTP extraction via standardized calls

⚡ Developer Benefits

Standardized MCP-based interactions for provisioning, SMS receipt, and extraction
Clear separation of concerns: numbers, messages, OTPs, and billing
Easy integration with multiple AI agents and workflows
Quick-start API key workflow and documentation (as per readme excerpt)

⚠️ Limitations

Source data notes real-US numbers via real-SIM; potential regulatory considerations not detailed here
Details on rate limits, uptime, and regional availability are not provided in the excerpt

@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):

json

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

3. Use It

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

"Provision a new phone number with area code 650 and wait for an OTP"

Tools

Tool	Description
`joltsms_list_numbers`	List active numbers with service labels, tags, and unread counts
`joltsms_get_number`	Full details for a single number
`joltsms_update_number`	Set service label, tags, or notes on a number
`joltsms_provision_number`	Rent a new dedicated real-SIM US number ($50/mo)
`joltsms_release_number`	Cancel/release a number at end of billing period
`joltsms_list_messages`	List recent SMS with parsed OTP codes
`joltsms_mark_read`	Mark single or bulk messages as read
`joltsms_wait_for_sms`	Poll until an SMS arrives (key tool for OTP flows)
`joltsms_get_latest_otp`	Get the most recent parsed verification code
`joltsms_billing_status`	Check all subscriptions with billing health

OTP Verification Workflow

The most common use case — automated phone verification:

code

1. joltsms_provision_number({ area_code: "650" })
   → Number provisioning started! Phone: +16505551234

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

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

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

5. joltsms_mark_read({ number_id: "+16505551234" })
   → Inbox clean

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

Environment Variables

Variable	Required	Description
`JOLTSMS_API_KEY`	Yes	Your API key (`jolt_sk_*`)
`JOLTSMS_API_URL`	No	API base URL (defaults to `https://api.joltsms.com`)

Requirements

Node.js 18+
A JoltSMS account with a payment method on file
Your first number must be ordered through the Dashboard to complete initial 3D Secure verification

Documentation

License

MIT

io.github.rchanllc/joltsms-sms