Kudosity MCP Server

An installable Model Context Protocol 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.

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

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

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

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

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:

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

License

MIT