WebSMS MCP Server for Claude

Send SMS messages directly from Claude using the WebSMS API. Built-in safeguards warn you about costs before sending.

View full documentation and examples →

Features

• Send SMS - Send single or bulk SMS messages
• Send OTP - Send verification codes with your company branding
• Phone Normalization - Automatically converts local formats to international:
  • New Zealand: 027 123 4567 → 64271234567
  • Australia: 0412 345 678 → 61412345678
• Cost Safeguards - Warns you about multi-segment messages and total cost before sending
• Rate Limiting - Built-in 10 messages/second rate limit

Installation

Choose either npm (recommended) or from source:

Option A: Install via npm (Recommended)

Add to your Claude Desktop configuration file:

{
  "mcpServers": {
    "websms": {
      "command": "npx",
      "args": ["@websms-nz/websms-mcp"],
      "env": {
        "WEBSMS_CLIENT_ID": "your-client-id",
        "WEBSMS_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

That's it! Claude will automatically download and run the MCP server.

Option B: Install from Source

# Clone the repository
git clone https://gitlab.com/icepicknz/websms-mcp.git

# Install dependencies and build
cd websms-mcp
npm install
npm run build

Then add to your Claude Desktop configuration:

{
  "mcpServers": {
    "websms": {
      "command": "node",
      "args": ["/path/to/websms-mcp/dist/index.js"],
      "env": {
        "WEBSMS_CLIENT_ID": "your-client-id",
        "WEBSMS_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Config File Locations

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Restart Claude Desktop

After saving the config, restart Claude Desktop and try: "Check my WebSMS balance"

Security - Protecting Your Credentials

Your API credentials are stored safely in the Claude Desktop config file, which is located in your user directory (not in any project folder):

| Platform | Config Location | |----------|----------------| | macOS | ~/Library/Application Support/Claude/claude_desktop_config.json | | Windows | %APPDATA%\Claude\claude_desktop_config.json | | Linux | ~/.config/Claude/claude_desktop_config.json |

NEVER store credentials in:

• .env files in project directories
• Any file that could be committed to git
• Shared or public repositories

Warning about .mcp.json: If you ask Claude to "add the MCP config" or "set up WebSMS", it may create a .mcp.json file in your project directory containing your credentials. This is extremely unsafe if your project is a git repository. Always check for and delete any .mcp.json files in project directories.

Add these to your .gitignore:

.env
.env.*
*.env
.mcp.json
.mcp/

If you accidentally expose your credentials: Immediately regenerate your API keys in the WebSMS Members Area.

Configuration

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | WEBSMS_CLIENT_ID | Yes | Your WebSMS client ID | | WEBSMS_CLIENT_SECRET | Yes | Your WebSMS client secret | | WEBSMS_SAFEGUARDS | No | Enable cost warnings (default: true) |

Getting API Credentials

1. Log in to WebSMS Members Area
2. Go to API Keys
3. Click Create New API Key
4. Copy the Client ID and Client Secret (secret shown only once!)

Available Tools

send_sms

Send a single SMS message.

Example prompts:

• "Send an SMS to 027 123 4567 and ask if they want coffee"
• "Text 021 987 6543 saying the delivery is on its way"
• "Send a message to +61412345678 about the meeting tomorrow"

Output:

Number normalized: 027 123 4567 -> 64271234567 (NZ)
Message: 28 characters (GSM)
Segments: 1 = 1 credit(s) ($0.10 NZD)

SMS sent successfully!
Message ID: msg_abc123

send_bulk_sms

Send to multiple recipients.

Example prompts:

• "Send a reminder to 021 123 4567, 022 987 6543, and 027 555 1234 about the meeting tomorrow"

Output:

Numbers normalized:
  021 123 4567 -> 64211234567 (NZ)
  022 987 6543 -> 64229876543 (NZ)
  027 555 1234 -> 64275551234 (NZ)

Message: 34 characters (GSM)
Segments per recipient: 1
Total: 3 credits ($0.30 NZD)

3 SMS sent successfully!

send_otp

Send a verification code.

Example prompts:

• "Send a verification code to 021 234 5678 for Acme Corp"

Output:

Number normalized: 021 234 5678 -> 64212345678 (NZ)

OTP sent successfully!
Code: 847291
Expires in: 600 seconds
Message ID: msg_otp123

check_balance

Check your account balance.

Output:

Balance: $45.50 NZD

lookup_number

Validate a phone number.

Output:

Number: 6421234567
Valid: Yes
Carrier: Spark
Country: NZ
Type: mobile

get_delivery_status

Check delivery status of a sent message.

Output:

Message ID: msg_abc123
Status: delivered
Delivered at: 2024-01-15T10:30:05Z

set_safeguards

Toggle cost warnings on/off.

Example: "Disable safeguards" or "Enable safeguards"

Phone Number Formats

The MCP automatically normalizes phone numbers:

| Input | Output | Country | |-------|--------|---------| | 027 123 4567 | 64271234567 | NZ | | 021 234 5678 | 64212345678 | NZ | | 0412 345 678 | 61412345678 | AU | | +64271234567 | 64271234567 | NZ | | 64271234567 | 64271234567 | NZ |

Message Segments & Cost

Messages are charged per segment:

| Encoding | Single Segment | Concatenated | |----------|---------------|--------------| | GSM (standard) | 160 chars | 153 chars/segment | | Unicode (emojis) | 70 chars | 67 chars/segment |

Each segment = 1 credit = $0.10 NZD

Safeguards

When safeguards are enabled (default), you'll see warnings like:

Warning: Message is 245 characters (Unicode detected).
This will be sent as 4 segments = 4 credits ($0.40 NZD).

To disable warnings:

• Set WEBSMS_SAFEGUARDS=false in environment, or
• Use the set_safeguards tool: "Disable safeguards"

Rate Limits

• MCP enforces 10 messages per second
• WebSMS API allows 100 requests per second

Support

• WebSMS Documentation: https://websms.co.nz/api/connexus/
• Contact: [email protected]