# clicksend/clicksend-mcp-server architecture

> Architecture diagram of the GitHub repository clicksend/clicksend-mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/clicksend/clicksend-mcp-server
- Repository: https://github.com/clicksend/clicksend-mcp-server

## Overview

##### Project type and purpose
- This is a Node.js/TypeScript-based MCP (Model Context Protocol) server whose sole purpose is to receive SMS/MMS send requests from an AI assistant (Claude Desktop) and forward them to ClickSend’s REST API.
- There is no database layer—just a CLI/daemon, environment-based configuration, and an external HTTP service.

##### Main components
a. Claude Desktop (Client)
- Initiates MCP requests via the configured MCP server.
b. Node.js MCP Server
- src/index.ts
- MCP protocol handler (stdin/stdout or local IPC)
- Configuration loader (reads CLICKSEND_USERNAME & CLICKSEND_API_KEY from env)
- HTTP client module that formats and sends REST requests to ClickSend
c. ClickSend REST API (External Service)
- Endpoints: /sms/send, /mms/send, etc.
d. Environment / Hosting
- Node.js Runtime (v18+)
- OS environment where the server is deployed (macOS or Windows user machine running Claude Desktop)
e. Package Management / Build

##### Relationships and data flows
- Protocol: MCP over stdin/stdout (JSON-RPC or CLI arguments)
- Payload: {"to":"+61411…", "message":"…"}
- Server reads environment variables at startup
- HTTP(S) POST with authentication headers (username/API key)
- Body: JSON with E.164 phone number and message
- HTTP response (status, message ID, errors)
- MCP response confirming delivery or error

##### Architectural patterns & design principles
- Single-responsibility: the server only handles message forwarding.
- Adapter/Facade: abstracts ClickSend’s REST interface behind an MCP interface.
- Configuration externalization: credentials injected via environment variables.
- Minimal layering: protocol handling layer, business logic layer, transport (HTTP) layer.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Claude["Claude Desktop (Client)"]:::external

    subgraph "Node.js MCP Server"
        Protocol["MCP Protocol Handler"]:::internal
        Config["Configuration Loader\n(env variables)"]:::internal
        HTTP["HTTP Client Module\n(ClickSend adapter)"]:::internal
        Pack["package.json"]:::support
        TSC["tsconfig.json"]:::support
    end

    ClickSend["ClickSend REST API"]:::external

    Claude -->|"MCP JSON-RPC"/stdin| Protocol
    Protocol -->|"reads env vars at startup"| Config
    Protocol -->|"HTTP POST /sms/send"| HTTP
    HTTP -->|"HTTP Response"| Protocol
    Protocol -->|"MCP Response"/stdout| Claude

    click Protocol "https://github.com/clicksend/clicksend-mcp-server/blob/main/src/index.ts"
    click Config "https://github.com/clicksend/clicksend-mcp-server/blob/main/src/index.ts"
    click HTTP "https://github.com/clicksend/clicksend-mcp-server/blob/main/src/index.ts"
    click Pack "https://github.com/clicksend/clicksend-mcp-server/blob/main/package.json"
    click TSC "https://github.com/clicksend/clicksend-mcp-server/blob/main/tsconfig.json"

    classDef internal fill:#bbdefb,stroke:#1e88e5,stroke-width:1px;
    classDef external fill:#c8e6c9,stroke:#2e7d32,stroke-width:1px;
    classDef support fill:#f0f0f0,stroke:#616161,stroke-width:1px;
```
