npm package: @sdsolutionsit/cast-mcp
Description: MCP server for the Cast.ph SMS platform
Latest version: 0.1.1

# @sdsolutionsit/cast-mcp

MCP server for the [Cast.ph](https://cast.ph) SMS platform. Exposes Cast's SMS APIs as AI-callable tools for Claude Desktop, Cursor, Claude Code, and any MCP client.

## Quick start

**Step 1 — Get your Cast API key** from the Cast.ph dashboard.

**Step 2 — Configure your MCP client** (see below).

**Step 3 — Start sending SMS with AI.**

---

## Client configuration

### Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "cast": {
      "command": "npx",
      "args": ["-y", "@sdsolutionsit/cast-mcp"],
      "env": {
        "CAST_API_KEY": "cast_your_key_here"
      }
    }
  }
}
```

### Claude Code

```bash
claude mcp add cast -- npx -y @sdsolutionsit/cast-mcp
```

Then set the env var:

```bash
export CAST_API_KEY=cast_your_key_here
```

### Cursor (`.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "cast": {
      "command": "npx",
      "args": ["-y", "@sdsolutionsit/cast-mcp"],
      "env": {
        "CAST_API_KEY": "cast_your_key_here"
      }
    }
  }
}
```

---

## Available tools

| Tool | Description |
|------|-------------|
| `cast_send_sms` | Send a single SMS via the promotional channel |
| `cast_send_otp` | Send an OTP/verification SMS via the high-priority channel |
| `cast_send_bulk_sms` | Send the same SMS to up to 1,000 recipients |
| `cast_get_balance` | Check account credit balance |
| `cast_get_sender_ids` | List approved sender IDs for the account |
| `cast_get_message_status` | Check delivery status of a sent message |
| `cast_get_message_logs` | Search message history with filters |

---

## Environment variables

| Variable | Required | Default |
|----------|----------|---------|
| `CAST_API_KEY` | Yes | — |
| `CAST_API_URL` | No | `https://api.cast.ph` |

The API key is never exposed to the AI — it stays inside the server process.

---

## Tool details

### cast_send_sms
Send a single SMS. Supports scheduling.

| Parameter | Required | Description |
|-----------|----------|-------------|
| `to` | Yes | Phone number in E.164 format (`+639171234567`) |
| `message` | Yes | SMS body |
| `sender_id` | No | Pre-approved sender ID. Omit to use account default. |
| `scheduled_at` | No | ISO 8601 UTC timestamp. Must be ≥30s in the future. |

### cast_send_otp
Send an OTP via the high-priority SMPP pool. Same parameters as `cast_send_sms` but without `scheduled_at`.

### cast_send_bulk_sms
Send to multiple recipients in one call. Credits reserved upfront; partial failures are refunded automatically.

| Parameter | Required | Description |
|-----------|----------|-------------|
| `to` | Yes | Comma-separated E.164 numbers (max 1,000) |
| `message` | Yes | SMS body sent to all recipients |
| `sender_id` | No | Pre-approved sender ID |

### cast_get_balance
No parameters. Returns credit balance and currency. 1 credit = 1 SMS part (160 chars).

### cast_get_sender_ids
No parameters. Returns all approved sender IDs. Call this before sending if the user wants to choose a sender.

### cast_get_message_status
Returns delivery status for a message ID (format: `CAST...`). DLRs are async — if status is `sent`, poll again in a few seconds.

### cast_get_message_logs
Search message history.

| Parameter | Description |
|-----------|-------------|
| `status` | Filter: `sent` or `failed` |
| `search` | Free-text across destination, message, ID, sender |
| `from` / `to` | Date range (`YYYY-MM-DD`) |
| `limit` | Max results (default 50, max 500) |
| `offset` | Pagination offset |

---

## Links

- [Cast.ph](https://cast.ph) — SMS platform
- [MCP Protocol](https://modelcontextprotocol.io) — Model Context Protocol spec
- [npm package](https://www.npmjs.com/package/@sdsolutionsit/cast-mcp)

## License

MIT