Kudosity 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