# Kudosity MCP Server

An installable [Model Context Protocol](https://modelcontextprotocol.io) server that gives AI agents native tools to send **SMS, MMS and WhatsApp** messages, manage contacts and webhooks, and research the Kudosity API — powered by [Kudosity](https://kudosity.com).

Runs locally (or in your own infrastructure), authenticates with your Kudosity API key, and exposes one clean tool per action — so an agent calls `send_sms` instead of hand-building HTTP requests.

## Tools

**Messaging**

| Tool | Type | Description |
|---|---|---|
| `send_sms` | write | Send an SMS to a recipient |
| `send_mms` | write | Send an MMS with a media attachment |
| `send_whatsapp` | write | Send a WhatsApp message (free-form text or approved template) |
| `get_message` | read | Get a sent message and its status by channel + ID |
| `list_messages` | read | List sent/received messages with delivery status; filter by status, direction (sent/replies), recipient, dates |

**Webhooks**

| Tool | Type | Description |
|---|---|---|
| `create_webhook` | write | Register an HTTPS webhook for delivery status, inbound messages, link hits, opt-outs |
| `list_webhooks` | read | List configured webhooks |
| `delete_webhook` | write | Delete a webhook by ID |

**Contacts & lists** *(require `KUDOSITY_API_SECRET`)*

| Tool | Type | Description |
|---|---|---|
| `create_list` | write | Create a contact list |
| `get_lists` | read | List all contact lists |
| `get_list` | read | Get a list and optionally its members |
| `add_contact_to_list` | write | Add a contact to a list |
| `remove_contact_from_list` | write | Remove a contact from a list |
| `delete_list` | write | Delete a contact list |

**Account** *(requires `KUDOSITY_API_SECRET`)*

| Tool | Type | Description |
|---|---|---|
| `get_balance` | read | Get your account balance |

**API discovery** — research the whole Kudosity API, always current

| Tool | Type | Description |
|---|---|---|
| `list_specs` | read | List the Kudosity API specifications |
| `list_endpoints` | read | List all endpoints for a spec |
| `search_endpoints` | read | Search the API by keyword |
| `get_endpoint` | read | Get full detail for one endpoint |

The discovery tools read the live specs from `developers.kudosity.com`, so they always reflect the latest published docs.

## Requirements

- Node.js 18+
- A Kudosity account and API key — **Settings → API Settings** in the Kudosity platform
- For contact and balance tools, also your API **secret** (same settings page)

## Install & configure

Runs via `npx` — no clone required.

### Claude Desktop / Claude Code

```json
{
  "mcpServers": {
    "kudosity": {
      "command": "npx",
      "args": ["-y", "kudosity-mcp"],
      "env": {
        "KUDOSITY_API_KEY": "your_api_key",
        "KUDOSITY_API_SECRET": "your_api_secret"
      }
    }
  }
}
```

`KUDOSITY_API_SECRET` is optional — omit it if you only need messaging, webhooks, and discovery. It's required for the contact-list and balance tools.

### Cursor — `.cursor/mcp.json`

```json
{
  "mcpServers": {
    "kudosity": {
      "command": "npx",
      "args": ["-y", "kudosity-mcp"],
      "env": { "KUDOSITY_API_KEY": "your_api_key", "KUDOSITY_API_SECRET": "your_api_secret" }
    }
  }
}
```

### VS Code — `.vscode/mcp.json`

```json
{
  "servers": {
    "kudosity": {
      "command": "npx",
      "args": ["-y", "kudosity-mcp"],
      "env": { "KUDOSITY_API_KEY": "your_api_key", "KUDOSITY_API_SECRET": "your_api_secret" }
    }
  }
}
```

## Usage examples

- *"Send an SMS to 61438333061 from KudosityDemo saying the order shipped."*
- *"Send the order_status_sample WhatsApp template to 61411122211."*
- *"List my delivered SMS from the last day."* / *"Show me inbound SMS replies."*
- *"Create a contact list called VIPs and add 61438333061."*
- *"Register a webhook at https://example.com/hook for SMS delivery status."*
- *"What's my account balance?"*
- *"Search the Kudosity API for anything about opt-outs."*

## Authentication

Kudosity has two API surfaces, and this server uses each where it's authoritative:

| Tools | Auth | Credentials |
|---|---|---|
| Messaging, webhooks, discovery | `x-api-key` header | `KUDOSITY_API_KEY` |
| Contact lists, balance | HTTP Basic | `KUDOSITY_API_KEY` + `KUDOSITY_API_SECRET` |

Credentials are read from environment variables and never written to disk. Treat them as secrets.

## Configuration

| Env var | Required | Default | Description |
|---|---|---|---|
| `KUDOSITY_API_KEY` | yes | — | Your Kudosity API key |
| `KUDOSITY_API_SECRET` | for contacts/balance | — | Your Kudosity API secret |
| `KUDOSITY_API_BASE_URL` | no | `https://api.transmitmessage.com` | Override the v2 API base URL |
| `KUDOSITY_V1_BASE_URL` | no | `https://api.transmitsms.com` | Override the v1 API base URL |

## Local development

```bash
git clone https://github.com/kudosity/mcp
cd mcp
npm install
npm run build
KUDOSITY_API_KEY=your_api_key npm start
```

Test tool listing with the MCP Inspector, or run the checks:

```bash
npm test              # mock integration tests (no credentials)
node test/discovery-test.mjs   # live spec-discovery test (no credentials)
```

## License

[MIT](./LICENSE)