Promotexter MCP 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