# engagelab-sms-mcp

An [MCP](https://modelcontextprotocol.io/) server that lets AI assistants send SMS messages through [EngageLab](https://www.engagelab.com/).

Add it to your MCP client (Cursor, Claude Desktop, etc.) and the AI can send template-based SMS on your behalf.

## Prerequisites

- Node.js 18+
- An EngageLab account with SMS API credentials (`dev_key` and `dev_secret`)
- At least one approved SMS template in your EngageLab console

## Quick Start

### Cursor

Go to **Settings > MCP**, click **Add new MCP server**, and paste:

```json
{
  "mcpServers": {
    "engagelab-sms": {
      "command": "npx",
      "args": ["-y", "engagelab-sms-mcp"],
      "env": {
        "ENGAGELAB_DEV_KEY": "<your_dev_key>",
        "ENGAGELAB_DEV_SECRET": "<your_dev_secret>"
      }
    }
  }
}
```

### Claude Desktop

Open **Settings > Developer > Edit Config** and add to `mcpServers`:

```json
{
  "mcpServers": {
    "engagelab-sms": {
      "command": "npx",
      "args": ["-y", "engagelab-sms-mcp"],
      "env": {
        "ENGAGELAB_DEV_KEY": "<your_dev_key>",
        "ENGAGELAB_DEV_SECRET": "<your_dev_secret>"
      }
    }
  }
}
```

### Other MCP Clients

Any MCP client that supports `stdio` transport can use this server. Point the command to `npx -y engagelab-sms-mcp` and pass the two required environment variables.

## Available Tools

### `send_sms`

Send SMS messages through EngageLab using a pre-approved template.

**Input:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `to` | `string[]` | Yes | Target phone numbers (international format recommended, e.g. `+8618700001111`) |
| `template.id` | `string` | Yes | Approved EngageLab SMS template ID |
| `template.params` | `object` | Yes | Template variable values, e.g. `{"code": "123456"}` |

**Example input:**

```json
{
  "to": ["+8618700001111"],
  "template": {
    "id": "your-template-id",
    "params": {
      "code": "123456"
    }
  }
}
```

**Output:**

| Field | Type | Description |
|-------|------|-------------|
| `success` | `boolean` | Whether the request was accepted |
| `plan_id` | `string` | EngageLab plan ID for tracking |
| `total_count` | `number` | Total recipients submitted |
| `accepted_count` | `number` | Recipients accepted for delivery |
| `message_id` | `string` | Message identifier (if available) |
| `message` | `string` | Status or error description |
| `code` | `number` | EngageLab response code (`0` = success) |

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `ENGAGELAB_DEV_KEY` | Yes | — | Your EngageLab dev key |
| `ENGAGELAB_DEV_SECRET` | Yes | — | Your EngageLab dev secret |
| `ENGAGELAB_BASE_URL` | No | `https://smsapi.engagelab.com` | API base URL |
| `ENGAGELAB_REQUEST_TIMEOUT_MS` | No | `10000` | Request timeout in milliseconds |
| `ENGAGELAB_MAX_RETRIES` | No | `1` | Max retry attempts for transient failures |

## Troubleshooting

**Server fails to start with "Missing required environment variable"**
- Make sure both `ENGAGELAB_DEV_KEY` and `ENGAGELAB_DEV_SECRET` are set in the `env` block of your MCP client config.

**`send_sms` returns error code 3002 ("invalid template id format")**
- Check that your template ID matches an approved template in the EngageLab console.

**`send_sms` returns error code related to template params**
- Verify that `template.params` keys match the variable names defined in your EngageLab template.

**SMS not received**
- Use international phone number format (e.g. `+8618700001111`).
- Confirm the template is approved and not suspended.

## Links

- [EngageLab SMS API Documentation](https://www.engagelab.com/docs/NEWSMS/REST-API/API-SMS-Sending)
- [Model Context Protocol](https://modelcontextprotocol.io/)

## License

MIT