Promotexter Server

A Model Context Protocol (MCP) server for integrating with the Promotexter SMS API. This server provides tools for sending SMS messages and checking account balance.

Features

• Balance Inquiry: Check your current Promotexter account balance with detailed information (available balance, account balance, credit limit, withheld amount)
• Single SMS Transaction: Send SMS messages to individual recipients

Installation

Using pip

pip install promotexter-mcp

Using uvx (recommended)

uvx promotexter-mcp

Quick Start

1. Get Your Promotexter Credentials

You'll need:

• API Key
• API Secret
• Sender ID (must be whitelisted in your Promotexter account)

Get these from your Promotexter dashboard at https://promotexter.com

2. Set Environment Variables

export PROMOTEXTER_API_KEY="your_api_key_here"
export PROMOTEXTER_API_SECRET="your_api_secret_here"
export PROMOTEXTER_SENDER_ID="your_sender_id_here"

Or create a .env file:

PROMOTEXTER_API_KEY=your_api_key_here
PROMOTEXTER_API_SECRET=your_api_secret_here
PROMOTEXTER_SENDER_ID=your_sender_id_here

3. Configure MCP Client

For Claude Desktop

Add to your MCP settings file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "promotexter": {
      "command": "uvx",
      "args": ["promotexter-mcp"],
      "env": {
        "PROMOTEXTER_API_KEY": "your_api_key_here",
        "PROMOTEXTER_API_SECRET": "your_api_secret_here",
        "PROMOTEXTER_SENDER_ID": "your_sender_id_here"
      }
    }
  }
}

Or using environment variables from your shell:

{
  "mcpServers": {
    "promotexter": {
      "command": "uvx",
      "args": ["promotexter-mcp"]
    }
  }
}

For Claude Code CLI

Add to your MCP settings:

{
  "mcpServers": {
    "promotexter": {
      "command": "uvx",
      "args": ["promotexter-mcp"],
      "env": {
        "PROMOTEXTER_API_KEY": "your_api_key_here",
        "PROMOTEXTER_API_SECRET": "your_api_secret_here",
        "PROMOTEXTER_SENDER_ID": "your_sender_id_here"
      }
    }
  }
}

Available Tools

get_balance

Get the current account balance from Promotexter.

Parameters: None

Returns:

• Available Balance
• Account Balance
• Credit Limit
• Withheld Amount

Example:

get_balance()

Response:

Available Balance: 486
Account Balance: 486
Credit Limit: 0
Withheld: 0

send_sms

Send a single SMS message via Promotexter.

Parameters:

• to (required): Recipient mobile number in international format (e.g., 639170000001)
• text (required): Message content (maximum 1000 characters)
• reference_id (optional): Your own reference ID for tracking

Note: The sender ID is configured via the PROMOTEXTER_SENDER_ID environment variable and must be whitelisted in your Promotexter account.

Returns: SMS send response with transaction details including:

• Message ID
• Remaining Balance
• Transaction Cost
• Unit Cost
• Message Parts count
• Operator Code
• Recipient number
• Sender ID
• Reference ID (if provided)

Example:

send_sms(
    to="639170000001",
    text="Hello! This is a test message.",
    reference_id="test-001"
)

Response:

SMS Sent Successfully!
Message ID: abc123...
Remaining Balance: 485.50
Transaction Cost: 0.50
Unit Cost: 0.50
Message Parts: 1
Operator: PHLSMART
To: 639170000001
From: DEMO
Reference ID: test-001

Development

Running Locally

1. Clone the repository:

git clone https://github.com/johnalvero/promotexter-mcp.git
cd promotexter-mcp

2. Install dependencies:

pip install -e .

3. Run the server:

python -m promotexter_mcp.server

Testing with MCP Inspector

fastmcp dev promotexter_mcp/server.py

API Documentation

For more information about the Promotexter API, visit:

• API Documentation: https://promotexter.docs.apiary.io/
• Promotexter Website: https://promotexter.com

Security Notes

• Never commit your API credentials to version control
• Use environment variables or secure credential management systems
• The sender ID must be whitelisted in your Promotexter account before use
• Ensure proper validation of recipient numbers before sending
• Test thoroughly in a development environment before production use

Error Handling

The server includes comprehensive error handling for:

• Missing or invalid credentials
• HTTP errors from the Promotexter API
• Invalid parameters
• Network timeouts
• Message length validation (max 1000 characters)
• Invalid phone number formats

Requirements

• Python 3.10 or higher
• fastmcp >= 2.13.0
• httpx >= 0.27.0

License

MIT License - see LICENSE file for details

Support

For issues related to:

• This MCP server: Open an issue at https://github.com/johnalvero/promotexter-mcp/issues
• Promotexter API: Contact Promotexter support at https://promotexter.freshdesk.com/

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Changelog

0.1.1 (2025-11-01)

• Updated documentation with correct installation instructions
• Added uvx support in configuration examples
• Improved README with detailed examples and responses
• Added package exclusions for cleaner distribution

0.1.0 (2025-11-01)

• Initial release
• Balance inquiry tool
• Single SMS transaction tool
• Environment-based configuration
• Comprehensive error handling