📱 LigueLead MCP Server

MCP Server para a API da LigueLead — SMS, SMS Flash e Campanhas de Voz (Brasil)

🇧🇷 Português

Tools disponíveis

Início rápido

git clone https://github.com/your-org/liguelead-mcp.git
cd liguelead-mcp
npm install
cp .env.example .env
# Edite .env com suas credenciais (painel: areadocliente.liguelead.app.br → Integrações → API Token)
npm run build
npm start

O servidor inicia em http://localhost:3000 por padrão.

Transportes

Configuração por cliente MCP

Claude Desktop (stdio)

Edite claude_desktop_config.json:

{
  "mcpServers": {
    "liguelead": {
      "command": "node",
      "args": ["/caminho/absoluto/para/liguelead-mcp/dist/index.js"],
      "env": {
        "LIGUELEAD_API_TOKEN": "seu-token",
        "LIGUELEAD_APP_ID": "seu-app-id",
        "TRANSPORT": "stdio"
      }
    }
  }
}

Claude Code

claude mcp add -s user liguelead \
  -e LIGUELEAD_API_TOKEN=seu-token \
  -e LIGUELEAD_APP_ID=seu-app-id \
  -e TRANSPORT=stdio \
  -- node /caminho/absoluto/para/liguelead-mcp/dist/index.js

Servidor HTTP remoto

Qualquer cliente MCP que suporte Streamable HTTP pode conectar via:

POST https://seu-servidor.com/mcp

Credenciais ficam no servidor — o cliente não precisa delas.

mcp-remote bridge

Para clientes que não suportam HTTP nativo (ex: Claude Desktop conectando a servidor remoto):

{
  "mcpServers": {
    "liguelead": {
      "command": "npx",
      "args": ["mcp-remote", "https://seu-servidor.com/mcp"]
    }
  }
}

Deploy

Docker

docker build -t liguelead-mcp .
docker run -d -p 3000:3000 \
  -e LIGUELEAD_API_TOKEN=seu-token \
  -e LIGUELEAD_APP_ID=seu-app-id \
  liguelead-mcp

Railway / Render

1. Conecte o repositório Git
2. Configure as variáveis de ambiente: LIGUELEAD_API_TOKEN, LIGUELEAD_APP_ID
3. Build command: npm install && npm run build
4. Start command: npm start

Segurança das credenciais

⚠️ Credenciais NUNCA ficam no código. O .env está no .gitignore.

Webhook

Configurar no painel LigueLead

1. Acesse areadocliente.liguelead.app.br
2. Vá em Integrações → API Token → Webhook URL
3. Insira: https://seu-servidor.com/webhook
4. Salve

Uma única URL recebe notificações de todos os canais (SMS, SMS Flash, Voz).

Consultar webhooks recebidos

# Via curl
curl http://localhost:3000/webhooks

# Ou abra no navegador
http://localhost:3000/webhooks

Retorna:

{
  "total": 42,
  "webhooks": [...]
}

⚠️ CRÍTICO: LigueLead NÃO faz retry. Se o endpoint falhar, a notificação é perdida permanentemente.

Referência das tools

send_sms

upload_voice_audio

Formatos aceitos: MP3, WAV. Máx: 50 MB.

send_voice_message

Janela de discagem: 08:00–21:44 (America/Sao_Paulo).

list_voice_uploads

Sem parâmetros. Lista todos os áudios enviados.

get_voice_upload

Estrutura do projeto

liguelead-mcp/
├── src/
│   ├── index.ts           # Entry point — HTTP ou stdio
│   ├── config.ts          # Validação de env vars (Zod) + loader .env
│   ├── lib/
│   │   ├── api-client.ts  # Client HTTP para API LigueLead
│   │   ├── validators.ts  # Schemas de telefone BR (Zod)
│   │   └── webhook.ts     # Webhook handler + GET /webhooks
│   └── tools/
│       ├── sms.ts         # Tool: send_sms
│       └── voice.ts       # Tools: voice (list/get/upload/send)
├── .env.example
├── .gitignore
├── Dockerfile
├── LICENSE
├── package.json
├── server.json
├── glama.json
├── tsconfig.json
└── README.md

Troubleshooting

🇺🇸 English

Available tools

Quick start

git clone https://github.com/your-org/liguelead-mcp.git
cd liguelead-mcp
npm install
cp .env.example .env
# Edit .env with your credentials (panel: areadocliente.liguelead.app.br → Integrações → API Token)
npm run build
npm start

Server starts at http://localhost:3000 by default.

Transports

MCP client configuration

Claude Desktop (stdio)

Edit claude_desktop_config.json:

{
  "mcpServers": {
    "liguelead": {
      "command": "node",
      "args": ["/absolute/path/to/liguelead-mcp/dist/index.js"],
      "env": {
        "LIGUELEAD_API_TOKEN": "your-token",
        "LIGUELEAD_APP_ID": "your-app-id",
        "TRANSPORT": "stdio"
      }
    }
  }
}

Claude Code

claude mcp add -s user liguelead \
  -e LIGUELEAD_API_TOKEN=your-token \
  -e LIGUELEAD_APP_ID=your-app-id \
  -e TRANSPORT=stdio \
  -- node /absolute/path/to/liguelead-mcp/dist/index.js

Remote HTTP server

Any MCP client supporting Streamable HTTP can connect via:

POST https://your-server.com/mcp

Credentials stay on the server — the client doesn't need them.

mcp-remote bridge

For clients without native HTTP support (e.g., Claude Desktop connecting to a remote server):

{
  "mcpServers": {
    "liguelead": {
      "command": "npx",
      "args": ["mcp-remote", "https://your-server.com/mcp"]
    }
  }
}

Deploy

Docker

docker build -t liguelead-mcp .
docker run -d -p 3000:3000 \
  -e LIGUELEAD_API_TOKEN=your-token \
  -e LIGUELEAD_APP_ID=your-app-id \
  liguelead-mcp

Railway / Render

1. Connect your Git repository
2. Set environment variables: LIGUELEAD_API_TOKEN, LIGUELEAD_APP_ID
3. Build command: npm install && npm run build
4. Start command: npm start

Credential security

⚠️ Credentials NEVER go in code. .env is in .gitignore.

Webhook

Configure in LigueLead panel

1. Go to areadocliente.liguelead.app.br
2. Navigate to Integrações → API Token → Webhook URL
3. Enter: https://your-server.com/webhook
4. Save

A single URL receives notifications from all channels (SMS, SMS Flash, Voice).

Query received webhooks

curl http://localhost:3000/webhooks

Returns:

{
  "total": 42,
  "webhooks": [...]
}

⚠️ CRITICAL: LigueLead does NOT retry webhooks. If the endpoint fails, the notification is permanently lost.

Tool reference

send_sms

upload_voice_audio

Accepted formats: MP3, WAV. Max: 50 MB.

send_voice_message

Dialing window: 08:00–21:44 (America/Sao_Paulo).

list_voice_uploads

No parameters. Lists all uploaded audio files.

get_voice_upload

Project structure

liguelead-mcp/
├── src/
│   ├── index.ts           # Entry point — HTTP or stdio
│   ├── config.ts          # Env var validation (Zod) + .env loader
│   ├── lib/
│   │   ├── api-client.ts  # HTTP client for LigueLead API
│   │   ├── validators.ts  # Brazilian phone schemas (Zod)
│   │   └── webhook.ts     # Webhook handler + GET /webhooks
│   └── tools/
│       ├── sms.ts         # Tool: send_sms
│       └── voice.ts       # Tools: voice (list/get/upload/send)
├── .env.example
├── .gitignore
├── Dockerfile
├── LICENSE
├── package.json
├── server.json
├── glama.json
├── tsconfig.json
└── README.md

Troubleshooting

License

MIT