46elks MCP Server

46elks MCP Server

MCP server for 46elks SMS API - Send SMS messages through Swedish telecommunications infrastructure.

Enable Claude Desktop, VS Code Copilot, and other MCP-compatible tools to send SMS messages through Sweden's leading SMS provider with native 46elks integration and built-in anti-spoofing protection.

⚠️ Disclaimer: This is an unofficial community project and is not affiliated with or endorsed by 46elks AB.

Getting Started

Prerequisites: You'll need Node.js 20+ (LTS recommended) and one of these MCP clients: Claude Desktop, VS Code with Copilot, or Cursor.

Step 1: Get 46elks Credentials

Before installing the MCP server, you'll need 46elks credentials:

1.1 Create Account & Add Funds

1. Sign up at 46elks.com
2. Complete verification process
3. Add funds to your account wallet - SMS sending requires account balance
4. Go to the 46elks dashboard

💰 Important: You need money in your 46elks wallet to send real SMS messages. Each SMS has a cost (typically ~0.50-1.00 SEK per message depending on destination).

1.2 Get API Credentials (NOT your account login)

1. In your 46elks dashboard, go to the Account tab
2. Look for the API section
3. Copy your API username (starts with u)
4. Copy your API password (starts with p)

⚠️ Important: Use your API credentials (found under Account → API), NOT your 46elks account login credentials. The API credentials are specifically for integrations like this MCP server.

1.3 Get Phone Number

1. In your dashboard, go to Phone Numbers
2. Purchase or note your existing phone number
3. Use the full international format (e.g., +46701234567)

Step 2: Install MCP Server

Step 3: Configure Your MCP Client

Choose your preferred MCP client:

Option A: Claude Desktop

Add this to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

Important: Replace /path/to/46elks-mcp-server with the actual path where you cloned the repository.

Option B: VS Code Copilot

Add this to your VS Code MCP configuration file:

macOS: ~/Library/Application Support/Code/User/mcp.json
Windows: %APPDATA%/Code/User/mcp.json

For detailed VS Code setup instructions, see: VS Code MCP Documentation

Available Tools

Note: This MCP server supports sending SMS and checking message history. You can send SMS and check for incoming replies using the get_sms_messages tool. Real-time SMS receiving (webhooks) is not implemented - use message history checking instead.

send_sms

Send SMS messages with validation and cost estimation.

Parameters:

• to (required): Recipient phone number in international format
• message (required): SMS message text
• from (optional): Custom sender ID or phone number (see security notes below)
• flashsms (optional): Set to "yes" for flash SMS (see Flash SMS limitations below)
• dryRun (optional): Override environment DRY_RUN setting

FROM Parameter Security:

• Default: Uses your configured ELKS_PHONE_NUMBER (recommended for replies)
• Custom Sender ID: Max 11 alphanumeric characters, must start with letter
• Phone Number: Any valid international number (⚠️ ensure you have permission)
• Validation: Blocks impersonation attempts (BANK, POLICE, etc.)
• Best Practice: Use your own business name or verified phone number

Examples:

⚠️ Flash SMS Note: Flash SMS may not display correctly on iPhone/iPad devices. See Flash SMS section below for device compatibility details.

🔒 Dry Run Safety: By default, DRY_RUN=true simulates SMS sending without actual delivery or charges. Set to false only when ready to send real messages.

get_sms_messages

Retrieve SMS message history with filtering options.

Parameters:

• direction (optional): "inbound", "outbound", or "both" (default: "both")
• limit (optional): Number of messages to retrieve (1-100, default: 10)

Examples:

💡 Checking Responses: Use this tool to check if someone has replied to your SMS! While not instant like a chat, you can easily see incoming messages to your 46elks phone number. Perfect for checking customer responses or confirmations.

check_sms_status

Check delivery status and details of sent messages.

Parameters:

• messageId (required): The message ID returned from send_sms

Example:

estimate_sms_cost

Get cost estimates without sending SMS.

Parameters:

• to (required): Recipient phone number
• message (required): SMS message text

check_account_balance

Verify 46elks account balance and information.

Example:

get_delivery_statistics

Analyze SMS delivery success rates and statistics.

Configuration Options

Environment Variables

Dry Run Mode (Cost Protection)

• Enabled (DRY_RUN=true):
  • SMS messages are simulated with realistic cost estimates
  • No actual messages sent or charges incurred
  • Perfect for testing and development
  • Default setting for safety
• Disabled (DRY_RUN=false):
  • SMS messages are actually sent through 46elks
  • Real charges apply to your account wallet
  • Only use when ready for production

⚠️ Cost Protection: We default to DRY_RUN=true to prevent accidental SMS sending and unexpected charges. This protects you from:

• Accidentally sending test messages to real numbers
• Incurring costs during development and testing
• Sending messages with wrong content or recipients

Recommended: Always test thoroughly with DRY_RUN=true before switching to false for production use.

SMS Costs & Limits

Message Costs

• Typical Cost: ~0.50-1.00 SEK per SMS (varies by destination)
• Multi-part Messages: Charged per SMS part (160 chars = 1 part, 320 chars = 2 parts)
• International: Higher rates for non-Swedish numbers
• Real-time Estimates: Use estimate_sms_cost tool for exact pricing

Message Limits

• Character Limits:
  • 160 characters (standard GSM characters)
  • 70 characters (with emojis/special characters)
• Rate Limits: 100 SMS per minute per account (enforced by 46elks API)
• Multi-part: Long messages automatically split and reassembled

Rate Limiting Behavior

• Enforcement: Rate limits are enforced by 46elks at the API level, not by our MCP server
• What Happens: If you exceed 100 SMS per minute, 46elks will return rate limit errors
• Bulk Operations: For large batches (CSV files, etc.), you'll need to pace your requests
• Recommendation: For bulk sending, send SMS in batches of 90-95 per minute with 1-minute pauses
• Error Handling: Rate limit errors are returned clearly with instructions to retry after waiting

Flash SMS

• Use Case: Urgent notifications that display immediately
• Behavior: Shows on screen instantly, not stored in inbox
• Cost: Same as regular SMS
• Device Compatibility:
  • ✅ Android: Displays as popup overlay (supported)
  • ❌ iPhone/iPad: Shows as regular SMS (not supported by iOS)
  • ✅ Feature Phones: Usually supported
  • ⚠️ Carrier-dependent: Some networks may not support Flash SMS

Important: Flash SMS is not supported by iPhone/iPad devices. iOS ignores the flash flag and displays Flash SMS messages as regular SMS messages in the Messages app.

Learn More:

• 46elks Flash SMS Tutorial - Complete guide to Flash SMS
• 46elks SMS API Documentation - Technical implementation details

Usage Examples

Basic SMS Sending

Check Message History

Cost Estimation

Account Management

Bulk SMS Operations

⚠️ Important: For large-scale SMS sending (100+ messages), we strongly recommend using 46elks' dedicated bulk SMS service instead of this MCP server.

Recommended for Bulk SMS:

• 46elks JustSend: justsend.46elks.com
• Features: CSV upload, scheduling, delivery reports, bulk pricing
• Benefits: No rate limits, optimized for large volumes, professional bulk tools

If Using This MCP Server for Small Batches (<100 SMS):

Small Batch Strategy (Under 100 SMS):

• Batch Size: Maximum 90 SMS per minute to stay under limits
• Time Required: ~1 minute per 90 messages + brief pauses
• Cost Planning: Use estimate_sms_cost for accurate pricing
• Safety First: Always test with DRY_RUN=true before sending
• Monitoring: Check account balance before starting

Why Use JustSend for Large Volumes:

• No Rate Limits: Send thousands of SMS efficiently
• CSV Support: Upload contact lists directly
• Professional Tools: Scheduling, templates, delivery tracking
• Bulk Pricing: Better rates for high volumes
• Reliability: Purpose-built for bulk operations

Testing

✅ Successfully tested with:

• Claude Desktop (macOS/Windows)
• VS Code Copilot (macOS/Windows)

⏳ Expected to work with:

• Cursor (not yet verified)
• Other MCP-compatible tools

Development

Local Setup

Project Structure

Security

API & Credential Security

• API credentials are passed through MCP client configuration (not stored in code)
• Dry run mode prevents accidental SMS sending during development
• Input validation prevents malicious phone numbers and messages
• No sensitive data is logged or stored

Enhanced Security Features

46elks Flexibility: 46elks provides excellent flexibility in sender ID options, allowing custom sender names and phone numbers for various business needs.

Our Additional Security Layer: To help users follow best practices and avoid common pitfalls, we've added responsible validation features:

• ✅ Smart Defaults: Uses your verified ELKS_PHONE_NUMBER as default sender for reliable delivery
• ✅ Best Practice Guidance: Helps avoid sender IDs that might be filtered (BANK, POLICE, etc.)
• ✅ Format Validation: Ensures sender IDs meet 46elks requirements (max 11 chars, must start with letter)
• ✅ Professional Recommendations: Encourages use of legitimate business names or owned numbers
• ✅ Permission Awareness: Alerts when using phone numbers as sender IDs

Benefits: These features help ensure:

• Better SMS delivery rates by following carrier best practices
• Professional appearance and brand consistency
• Compliance with SMS regulations and carrier guidelines
• Reduced risk of messages being filtered or blocked

This approach enhances 46elks' powerful API with additional guidance for optimal results.

Troubleshooting

Common Issues

Error: "Missing required environment variables"

• Check your MCP client configuration file
• Ensure all required environment variables are set
• Verify file paths are absolute paths

Error: "Invalid phone number format"

• Use international format: +46701234567
• Don't use spaces or dashes in phone numbers

Messages not sending (DRY_RUN=false)

• Verify 46elks account has sufficient balance
• Check phone number is valid and not blocked
• Ensure 46elks account is in good standing

Rate Limit Errors (429 responses)

• You've exceeded 100 SMS per minute - wait 1 minute before retry
• For bulk operations: pace requests to 90-95 SMS per minute
• Use cost estimation tools to plan large batches before sending
• Consider implementing delays between messages for CSV bulk operations

MCP Server Best Practices (Small Batches Only)

• Recommended Limit: Use this MCP server for <100 SMS at a time
• Large Operations: Use justsend.46elks.com for bulk SMS instead
• Rate Limits: Stay under 90 SMS per minute if using MCP server
• Testing: Always test with DRY_RUN=true before any batch sending

Build errors

• Ensure Node.js 20+ LTS is installed (Node.js 18 is End of Life)
• Run npm install to install dependencies
• Delete node_modules and package-lock.json, then npm install

Getting Help

For 46elks API, account, pricing, and service questions:

• Visit: 46elks.com/support
• Official 46elks documentation: 46elks.com/docs

For bulk SMS sending or CSV upload:

• Use 46elks' dedicated service: justsend.46elks.com

For MCP server issues:

1. Check the Issues page for this project
2. Check MCP documentation for your client (Claude Desktop, VS Code, etc.)

Contributing

Bug reports and pull requests are welcome on GitHub. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

This project is licensed under the MIT License - see the LICENSE file for details.

⚠️ Disclaimer: This is an unofficial community project and is not affiliated with or endorsed by 46elks AB. 46elks is a registered trademark of 46elks AB.

🇸🇪 Made for the Swedish developer community with ❤️ for AI-powered SMS automation.