promotexter-mcp 0.1.0

MCP server for Promotexter SMS API - Send SMS and check balance via Model Context Protocol

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
• Single SMS Transaction: Send SMS messages to individual recipients

Installation

1. Clone this repository or create the files in your project directory

2. Install dependencies:

pip install -e .

Or install directly:

pip install mcp httpx

Configuration

Environment Variables

Set the following environment variables with your Promotexter API credentials:

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

You can also add these to a .env file:

PROMOTEXTER_API_KEY=your_api_key_here
PROMOTEXTER_API_SECRET=your_api_secret_here
PROMOTEXTER_SENDER_ID=your_sender_id_here

MCP Settings

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

{
  "mcpServers": {
    "promotexter": {
      "command": "python",
      "args": ["/path/to/promotexter-mcp/promotexter_server.py"],
      "env": {
        "PROMOTEXTER_API_KEY": "your_api_key_here",
        "PROMOTEXTER_API_SECRET": "your_api_secret_here",
        "PROMOTEXTER_SENDER_ID": "your_sender_id_here"
      }
    }
  }
}

Or if you want to use environment variables from your shell:

{
  "mcpServers": {
    "promotexter": {
      "command": "python",
      "args": ["/path/to/promotexter-mcp/promotexter_server.py"]
    }
  }
}

Available Tools

get_balance

Get the current account balance from Promotexter.

Parameters: None

Returns: Account balance information

Example:

get_balance()

send_sms

Send a single SMS message via Promotexter.

Parameters:

• to (required): Recipient mobile number (must be valid mobile number format)
• text (required): Message content (maximum 1000 characters)
• reference_id (optional): Optional 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
• Message parts count
• Operator code

Example:

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

API Documentation

For more information about the Promotexter API, visit: https://promotexter.docs.apiary.io/

Security Notes

• Never commit your API credentials to version control
• Use environment variables or secure credential management
• The sender ID (configured via PROMOTEXTER_SENDER_ID) must be whitelisted in your Promotexter account
• Ensure proper validation of recipient numbers before sending

Error Handling

The server includes comprehensive error handling for:

• Missing or invalid credentials
• HTTP errors from the API
• Invalid parameters
• Network timeouts
• Message length validation

Development

To run the server directly:

python promotexter_server.py

Requirements

• Python 3.10+
• mcp >= 1.0.0
• httpx >= 0.27.0

License

MIT

Support

For issues related to:

• The MCP server: Open an issue in this repository
• Promotexter API: Contact Promotexter support at https://promotexter.freshdesk.com/