# 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

```bash
pip install promotexter-mcp
```

### Using uvx (recommended)

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

```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"
```

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

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

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

#### For Claude Code CLI

Add to your MCP settings:

```json
{
  "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:**
```python
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:**
```python
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:
```bash
git clone https://github.com/johnalvero/promotexter-mcp.git
cd promotexter-mcp
```

2. Install dependencies:
```bash
pip install -e .
```

3. Run the server:
```bash
python -m promotexter_mcp.server
```

### Testing with MCP Inspector

```bash
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](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