MCP 服务器

Promotexter MCP Server

Integrates with the Promotexter SMS API to enable sending single SMS messages and performing detailed account balance inquiries. It provides a secure way for models to manage SMS communications and track transaction costs and credits.

README

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

Clone the repository:

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

Install dependencies:

pip install -e .

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/