rchanllc/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):
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."
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_list_payment_methods | List masked saved cards and payment method IDs |
| joltsms_provision_number | Rent the next available number, optionally using a selected saved card ($50/mo) |
| joltsms_release_number | End auto-renew at period end, or cancel an unpaid initial checkout |
| joltsms_list_messages | List recent SMS with parsed OTP codes and message IDs |
| joltsms_reply_to_sms | Reply to an eligible inbound message (up to 15 characters) |
| 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 up to 10 subscriptions with billing health |
OTP Verification Workflow
The most common use case — automated phone verification:
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 22+
- 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
Upgrading from 1.x
Use Node.js 22 or newer, 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