kudosity-mcp

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