Metadata-Version: 2.4
Name: promotexter-mcp
Version: 0.1.0
Summary: MCP server for Promotexter SMS API - Send SMS and check balance via Model Context Protocol
Project-URL: Homepage, https://github.com/johnalvero/promotexter-mcp
Project-URL: Documentation, https://github.com/johnalvero/promotexter-mcp#readme
Project-URL: Repository, https://github.com/johnalvero/promotexter-mcp
Project-URL: Issues, https://github.com/johnalvero/promotexter-mcp/issues
Author-email: John Alvero <johnalvero@example.com>
License: MIT
License-File: LICENSE
Keywords: api,mcp,messaging,model-context-protocol,promotexter,sms
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: fastmcp>=2.13.0
Requires-Dist: httpx>=0.27.0
Description-Content-Type: text/markdown

# 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:
```bash
pip install -e .
```

Or install directly:
```bash
pip install mcp httpx
```

## Configuration

### Environment Variables

Set the following environment variables with your Promotexter API credentials:

```bash
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):

```json
{
  "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:
```json
{
  "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:
```bash
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/
