@lionchat/mcp-server

MCP server que conecta agentes de IA a plataforma LionChat. Expoe mais de 547 ferramentas para gerenciar contatos, conversas, kanban, funis, mensagens, automacoes e muito mais.

v0.2.0 — Multi-conta via account_id opcional, 18 campos novos no AI Agente (Captain), playground e tools list, FAQs com assistant_id, reports com filtros completos. Veja CHANGELOG.md.

O que e MCP?

MCP (Model Context Protocol) e um protocolo aberto que permite agentes de IA interagirem com servicos externos. Com este servidor, qualquer agente compativel (Claude Code, n8n, agentes customizados) pode executar acoes no LionChat por linguagem natural.

Sem MCP: Voce le a documentacao, copia endpoints, configura manualmente. Com MCP: Voce diz "crie um funil com 4 etapas" e o agente faz tudo.

Inicio Rapido

1. Obtenha seu token

1. Faca login no LionChat
2. Va em Configuracoes > Perfil
3. Copie o Access Token

2. Descubra seu Account ID

O account_id aparece na URL quando voce esta logado:

app.lionchat.com.br/app/accounts/ACCOUNT_ID/dashboard

3. Conecte ao Claude Code

claude mcp add lionchat \
  -e LIONCHAT_API_TOKEN=seu_token \
  -e LIONCHAT_ACCOUNT_ID=123 \
  -- npx @lionchat/mcp-server

Pronto. Agora voce pode pedir ao Claude Code para fazer qualquer coisa no LionChat.

Instalacao alternativa (variaveis de ambiente)

export LIONCHAT_API_TOKEN=seu_token
export LIONCHAT_ACCOUNT_ID=123
npx @lionchat/mcp-server

Instancia self-hosted / white-label

export LIONCHAT_BASE_URL=https://sua-instancia.com
npx @lionchat/mcp-server

Configuracao

Prioridade: argumentos CLI > variaveis de ambiente > valores padrao.

Trabalhando com multiplas contas

Toda ferramenta aceita um parametro opcional account_id que sobrepoe a variavel LIONCHAT_ACCOUNT_ID da sessao atual. Util para agentes que precisam consultar/operar em mais de uma conta sem reiniciar o MCP.

"Lista contatos da conta padrao": lionchat_contacts_list
"Lista contatos da conta 42":     lionchat_contacts_list(account_id="42")

Se account_id nao for informado, o MCP usa o valor de LIONCHAT_ACCOUNT_ID (ou --account=). O token (LIONCHAT_API_TOKEN) precisa ter acesso a todas as contas que voce quer chamar.

Filtro por Categoria

Para melhor performance do agente, carregue apenas as ferramentas que precisa:

npx @lionchat/mcp-server --categories=contacts,conversations,kanban_items

Perfis Sugeridos

Categorias Disponiveis

O que o MCP pode fazer por voce

O MCP transforma o LionChat em uma plataforma controlavel por IA. Em vez de clicar em menus e preencher formularios, voce fala o que precisa e o agente faz.

Gestao de Contatos e CRM

"Importa esses 50 leads que recebi hoje e adiciona a label 'Evento Marco 2026' em todos"

"Busca todos os contatos que tem 'advogado' no campo profissao e cria um segmento"

"Mescla o contato duplicado do Joao — o ID 45 e o ID 128 sao a mesma pessoa"

"Quais contatos novos entraram essa semana? Me da um resumo por canal de origem"

Kanban e Funil de Vendas

"Cria um funil chamado 'Lancamento Produto X' com as etapas:
 Interesse, Qualificacao, Proposta Enviada, Negociacao, Fechado Ganho, Perdido"

"Pega todos os cards que estao na etapa 'Qualificacao' ha mais de 7 dias e move pra 'Perdido'"

"Cria um card no funil de Vendas pra cada contato que tem a label 'Lead Quente'"

"Qual o valor total dos cards na etapa 'Proposta Enviada'? E quantos tem?"

"Atribui o agente Maria a todos os cards do funil 'Suporte Tecnico'"

Conversas e Atendimento

"Quantas conversas abertas eu tenho agora? Separa por time"

"Pega as 10 conversas mais antigas sem resposta e atribui ao time de Suporte"

"Envia 'Ola! Como posso ajudar?' na conversa 234"

"Fecha todas as conversas resolvidas que estao paradas ha mais de 48 horas"

"Agenda uma mensagem pra amanha as 9h na conversa 56: 'Bom dia! Tudo bem com o orcamento?'"

Automacoes e Regras

"Cria uma automacao: quando uma conversa receber a label 'Urgente',
 atribuir ao time Premium e enviar notificacao"

"Lista todas as minhas regras de automacao ativas"

"Duplica a automacao 'Boas-vindas VIP' e muda o time de destino pra 'Vendas B2B'"

Agenda e Tarefas

"Cria uma tarefa pra ligar pro Joao amanha as 14h"

"Quais tarefas estao pendentes pra hoje?"

"Cancela todas as tarefas de follow-up da semana passada que nao foram feitas"

"Agenda uma reuniao com o contato 45 pra quinta-feira as 10h"

Mensagens e Templates WhatsApp

"Lista os templates WhatsApp aprovados"

"Agenda o envio do template 'Lembrete Pagamento' pra todos os contatos com label 'Inadimplente'"

"Envia uma imagem do produto novo na conversa 89 com a legenda 'Confira nossa novidade!'"

Relatorios e Metricas

"Qual foi o tempo medio de primeira resposta essa semana?"

"Me da o relatorio de desempenho dos agentes do mes passado"

"Quantas conversas cada inbox recebeu nos ultimos 30 dias?"

"Qual a nota media do CSAT esse mes? Compara com o mes anterior"

"Quais agentes estao online agora e quantas conversas cada um tem?"

Grupos WhatsApp

"Lista todos os grupos WhatsApp da inbox 5"

"Adiciona o numero 5511999887766 no grupo 'Clientes Premium'"

"Qual o link de convite do grupo 'Suporte Tecnico'?"

"Remove o participante 5511888776655 do grupo 'Equipe Interna'"

IA e Assistentes

"Lista meus assistentes de IA configurados"

"Pede pro assistente 'Vendas' sugerir uma resposta pra conversa 123"

"Resume a conversa 456 em 3 pontos principais"

"Adiciona a URL https://empresa.com/faq na base de conhecimento do assistente"

"Cria um AI Agente 'Closer' com modelo gpt-4o, temperatura 0.4,
 ativa FAQ e citation, follow-up depois de 30 minutos"

Criar/Atualizar AI Agente — campos disponiveis (v0.2.0)

lionchat_captain_assistants_create e _update agora suportam dot-notation para campos aninhados em config. Exemplos:

{
  "name": "Closer Black Friday",
  "description": "Agente de fechamento de vendas",
  "response_guidelines": ["Seja direto", "Use prova social"],
  "guardrails": ["Nao prometa desconto sem aprovacao"],
  "config.model": "gpt-4o",
  "config.temperature": 0.4,
  "config.instructions": "Voce e um closer especialista...",
  "config.feature_faq": true,
  "config.feature_memory": true,
  "config.feature_citation": true,
  "config.welcome_message": "Oi! Vi que voce tem interesse...",
  "config.min_response_time": 5,
  "config.max_response_time": 15,
  "config.feature_follow_up": true,
  "config.follow_up_time": 30,
  "config.follow_up_prompt": "Pergunte se ainda tem duvida.",
  "config.disabled_tools": ["create_kanban_item"],
  "config.offer_ids": [12, 17],
  "config.media_asset_ids": [3],
  "config.booking_event_type_ids": [5]
}

Tambem novos:

VoIP e Ligacoes

"Qual o saldo do meu VoIP?"

"Lista as ultimas 20 ligacoes recebidas"

"Transcreve a ligacao 78 e me da o resumo"

"Analisa a ligacao 92 — o cliente ficou satisfeito?"

Operacoes em Massa

"Pega todos os contatos com label 'Inativo' e remove a label"

"Move todos os cards do agente Pedro pro agente Ana (ele saiu de ferias)"

"Adiciona a label 'Black Friday' em todos os contatos que compraram em novembro"

"Exporta todos os cards do funil 'Vendas Q1' pra eu analisar"

Exemplos rapidos (comando e ferramenta usada)

No n8n

O n8n suporta MCP de duas formas:

Opcao 1: MCP Client + AI Agent (recomendado para decisoes inteligentes)

1. Adicione um node "AI Agent" ao seu workflow (Claude, GPT, ou outro LLM)
2. Adicione um node "MCP Client" como ferramenta do agente
3. Configure o MCP Client:
   • Transport: stdio
   • Command: npx
   • Arguments: @lionchat/mcp-server
   • Environment Variables:
     • LIONCHAT_API_TOKEN = seu token
     • LIONCHAT_ACCOUNT_ID = seu account ID
     • LIONCHAT_CATEGORIES = categorias desejadas (opcional)
4. Conecte o MCP Client ao AI Agent
5. O agente de IA decide automaticamente quais ferramentas usar

Exemplo de prompt no AI Agent:

"Analise os contatos criados ontem. Se algum tem empresa no nome, crie um card no funil 'Vendas B2B' na etapa 'Prospeccao'."

O agente vai chamar lionchat_contacts_list, analisar os resultados, e chamar lionchat_kanban_items_create para cada contato relevante.

Opcao 2: HTTP Request (para automacoes fixas)

Para automacoes tipo "se X entao Y" sem necessidade de IA, use o node HTTP Request do n8n chamando a API do LionChat diretamente:

• URL: https://app.lionchat.com.br/api/v1/accounts/{account_id}/contacts
• Header: api_access_token: seu_token
• Method: GET, POST, etc.

Quando usar cada opcao

Em scripts ou agentes customizados

O MCP server funciona com qualquer cliente MCP via transporte stdio. Execute como subprocesso e comunique via stdin/stdout (JSON-RPC).

Ferramentas Meta

Sempre disponiveis, independente do filtro de categorias:

Use lionchat_ping para verificar se a conexao esta funcionando antes de executar outras acoes.

API Publica

Os 12 endpoints da API publica (widget, contatos publicos, CSAT) sao ocultos por padrao por seguranca. Para habilitar:

npx @lionchat/mcp-server --include-public-api

Esses endpoints usam inbox_identifier e contact_identifier em vez de token. Habilite apenas se seu agente precisa criar contatos ou conversas em nome de usuarios finais.

Upload de Arquivos

Endpoints que requerem upload de arquivo (importacao CSV, avatar, anexos) estao incluidos mas retornam uma mensagem orientando a usar a interface web ou chamadas API diretas. Upload via MCP sera suportado em versoes futuras.

Seguranca

• Token armazenado em variavel de ambiente, nunca logado ou incluido em respostas
• Transporte stdio -- comunicacao local entre processos, sem porta de rede aberta
• Stateless -- nada salvo em disco
• Timeout de 30 segundos por requisicao
• Retry automatico com backoff exponencial para rate limiting (429)
• Cada requisicao usa o token do cliente -- permissoes do LionChat sao respeitadas no servidor

Recomendacao: Use um token com permissoes minimas para seu caso de uso. Evite tokens de administrador em agentes automatizados.

Requisitos

• Node.js 18 ou superior
• Conta no LionChat com access token

Desenvolvimento

# Clonar o repositorio
git clone https://github.com/LionChatCRM/lionchat-mcp-server-.git
cd lionchat-mcp-server-

# Instalar dependencias
npm install

# Build
npm run build

# Testar localmente
LIONCHAT_API_TOKEN=seu_token LIONCHAT_ACCOUNT_ID=123 node dist/index.js

Atualizar endpoints

Quando a API do LionChat mudar:

1. Atualize o HTML de documentacao da API
2. Execute npm run extract -- caminho/para/api-docs.html
3. Verifique o endpoints.json gerado
4. Incremente a versao no package.json
5. npm publish

Licenca

MIT