clicksend mcp

Local 2025-08-31 23:25:51 0

This server enables AI models to send SMS messages and initiate Text-to-Speech calls programmatically using ClickSend's API with built-in rate limiting and input validation.

A Model Context Protocol (MCP) server that provides SMS messaging and Text-to-Speech (TTS) call capabilities through ClickSend's API. This server enables AI models to send SMS messages and initiate voice calls programmatically.

Features

SMS Messaging: Send SMS messages to any phone number worldwide
Text-to-Speech Calls: Make voice calls with customizable text-to-speech messages
Rate Limiting: Built-in protection with 5 actions per minute limit
Input Validation: Comprehensive validation for phone numbers and message content
Error Handling: Detailed error messages and proper error propagation

Installation

Prerequisites

Node.js (v16 or higher)
ClickSend account with API credentials
MCP-compatible Client

Setup

Clone the repository:

git clone https://github.com/J-Gal02/clicksend-mcp.git
cd clicksend-mcp

Install dependencies:
```
npm install
```
Build the project:
```
npm run build
```

Setting up the MCP Client

Add the following sections into your cline_mcp_settings.json file or claude_desktop_config.json file.

Be sure to replace the directory with the correct path to the build folder, as shown in the example below, as well as the username and API key with your own.

{
    "mcpServers": {
        "clicksend": {
            "command": "node",
            "args": ["/directory/to/build/folder/clicksend-mcp/build/index.js"],
            "env": {
                "CLICKSEND_USERNAME": "[email protected]",
                "CLICKSEND_API_KEY": "ZZZZZZZZ-YYYY-YYYY-YYYY-XXXXXXXXXXXX"
            }
        }
    }
}

Usage

Available Tools

1. send_sms

Send SMS messages to specified phone numbers.

Parameters: - to: Phone number in E.164 format (e.g., +61423456789) - message: Text content to send

Example:

{
  "name": "send_sms",
  "arguments": {
    "to": "+61423456789",
    "message": "Hello from ClickSend MCP!"
  }
}

2. make_tts_call

Initiate Text-to-Speech calls.

Parameters: - to: Phone number in E.164 format - message: Text content to convert to speech - voice: Voice type ('female' or 'male', defaults to 'female')

Example:

{
  "name": "make_tts_call",
  "arguments": {
    "to": "+61423456789",
    "message": "This is a Text-to-Speech call from ClickSend MCP",
    "voice": "female"
  }
}

Rate Limiting

The server implements a rate limit of 5 actions per minute to prevent abuse. Requests exceeding this limit will receive an error response with a retry delay suggestion.

Development

Available Scripts

npm run build: Compile TypeScript and make the output executable
npm run start: Start the MCP server
npm run dev: Run TypeScript compiler in watch mode

Project Structure

clicksend-mcp/
├── src/
│   ├── index.ts        # Main server implementation
│   ├── client.ts       # ClickSend API client
│   └── utils/
│       └── validation.ts # Input validation utilities
├── build/              # Compiled JavaScript output
└── package.json        # Project configuration

Error Handling

The server provides detailed error messages for various scenarios:

Invalid phone numbers
Message content validation failures
Rate limit exceeded
API authentication errors
Network connectivity issues

Error responses include appropriate error codes and descriptive messages to help diagnose issues.

TODO

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

[
  {
    "description": "Send SMS messages via ClickSend",
    "inputSchema": {
      "additionalProperties": false,
      "properties": {
        "message": {
          "description": "Message content to send",
          "type": "string"
        },
        "to": {
          "description": "Phone number in E.164 format (e.g. +61423456789)",
          "type": "string"
        }
      },
      "required": [
        "to",
        "message"
      ],
      "type": "object"
    },
    "name": "send_sms"
  },
  {
    "description": "Make Text-to-Speech calls via ClickSend",
    "inputSchema": {
      "additionalProperties": false,
      "properties": {
        "message": {
          "description": "Text content to convert to speech",
          "type": "string"
        },
        "to": {
          "description": "Phone number in E.164 format",
          "type": "string"
        },
        "voice": {
          "default": "female",
          "description": "Voice type for TTS",
          "enum": [
            "female",
            "male"
          ],
          "type": "string"
        }
      },
      "required": [
        "to",
        "message"
      ],
      "type": "object"
    },
    "name": "make_tts_call"
  }
]