Labsco
rafabarbosa logo

Webhooks MCP

from rafabarbosa

Send HTTP requests to webhooks with dynamic parameters.

🔥🔥✓ VerifiedFreeAdvanced setup
#email#automation#crm#slack#devops#git

Webhooks MCP

Um servidor MCP (Model Context Protocol) para enviar requisições HTTP para webhooks com parâmetros dinâmicos.

Funcionalidades

  • ✅ Suporte a todos os métodos HTTP: GET, POST, PUT, PATCH, DELETE
  • ✅ Parâmetros dinâmicos de qualquer tipo (nome, email, telefone, etc.)
  • ✅ Headers HTTP personalizados
  • ✅ Timeout configurável
  • ✅ Validação de entrada com Zod
  • ✅ Tratamento de erros detalhado
  • ✅ Logs de requisição e resposta

Instalação

  1. As dependências já estão instaladas. Para reinstalar se necessário:
cd webhooks-mcp
npm install
  1. Compile o TypeScript:
npm run build

Configuração no Claude Desktop

Adicione a seguinte configuração no arquivo claude_desktop_config.json:

{
  "mcpServers": {
    "webhooks": {
      "command": "node",
      "args": ["/Users/rafabarbosa/Desktop/scripts/webhooks-mcp/dist/index.js"]
    }
  }
}

Localização do arquivo de configuração:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Uso

Ferramenta Disponível

send_webhook

Envia uma requisição HTTP para um webhook com parâmetros personalizados.

Parâmetros:

  • url (obrigatório): URL do webhook (ex: https://meuwebhook.com.br)
  • method (obrigatório): Método HTTP (GET, POST, PUT, PATCH, DELETE)
  • parameters (opcional): Objeto com parâmetros de qualquer tipo
  • headers (opcional): Headers HTTP adicionais
  • timeout (opcional): Timeout em milissegundos (padrão: 30000)

Exemplos de Uso

1. POST com dados de usuário

{
  "url": "https://meuwebhook.com.br/usuarios",
  "method": "POST",
  "parameters": {
    "nome": "João Silva",
    "email": "joao@email.com",
    "telefone": "11999999999",
    "idade": 30,
    "ativo": true
  }
}

2. GET com query parameters

{
  "url": "https://api.exemplo.com/dados",
  "method": "GET",
  "parameters": {
    "filtro": "ativo",
    "limite": 10,
    "pagina": 1
  }
}

3. PUT com headers personalizados

{
  "url": "https://api.exemplo.com/atualizar/123",
  "method": "PUT",
  "parameters": {
    "nome": "João Santos",
    "status": "atualizado"
  },
  "headers": {
    "Authorization": "Bearer token123",
    "X-Custom-Header": "valor"
  }
}

4. DELETE simples

{
  "url": "https://api.exemplo.com/deletar/123",
  "method": "DELETE"
}

Comportamento por Método HTTP

  • GET/DELETE: Parâmetros são enviados como query parameters na URL
  • POST/PUT/PATCH: Parâmetros são enviados no body da requisição como JSON

Tratamento de Erros

O MCP trata diferentes tipos de erro:

  • Erros de validação: Quando os parâmetros não estão no formato correto
  • Erros HTTP: Quando o webhook retorna status de erro (4xx, 5xx)
  • Erros de rede: Timeout, conexão recusada, etc.

Desenvolvimento

Scripts disponíveis

  • npm run build: Compila o TypeScript
  • npm run dev: Compila em modo watch
  • npm start: Executa o servidor compilado

Estrutura do projeto

webhooks-mcp/
├── src/
│   └── index.ts          # Servidor MCP principal
├── dist/                 # Arquivos compilados
├── examples.json         # Exemplos de uso
├── claude_desktop_config.json  # Configuração de exemplo
├── package.json
├── tsconfig.json
└── README.md

Testando o Servidor

Para testar se o servidor está funcionando:

# Compilar
npm run build

# Testar execução (pressione Ctrl+C para sair)
node dist/index.js

# Rodar testes automatizados
npm test

# Os exemplos do arquivo examples.json são validados automaticamente por testes automatizados.

Logs

O servidor gera logs detalhados:

  • Requisições enviadas (método, URL, parâmetros)
  • Respostas recebidas (status, tempo de resposta)
  • Erros detalhados com contexto

Segurança

  • Validação rigorosa de entrada com Zod
  • Headers de User-Agent identificando o MCP
  • Timeout configurável para evitar requisições infinitas
  • Tratamento seguro de erros sem exposição de dados sensíveis
  • Whitelist de URLs/domínios: configure a variável de ambiente WHITELIST_URLS (separada por vírgula) para restringir os destinos permitidos. Exemplo:
export WHITELIST_URLS="api.exemplo.com,https://hooks.slack.com"

Se não configurada, qualquer URL será permitida.

  • Níveis de log configuráveis: defina a variável de ambiente LOG_LEVEL para controlar a verbosidade dos logs (debug, info, warn, error). Exemplo:
export LOG_LEVEL="debug"
  • Retentativas automáticas: defina as variáveis de ambiente RETRY_ATTEMPTS (número de tentativas, padrão 1) e RETRY_BASE_DELAY_MS (delay inicial em ms, padrão 500) para habilitar retentativas automáticas com backoff exponencial em falhas temporárias.
export RETRY_ATTEMPTS=3
export RETRY_BASE_DELAY_MS=1000
  • Internacionalização (i18n): defina a variável de ambiente LANG como pt (padrão) ou en para receber mensagens em português ou inglês.
export LANG=en

Exemplos de Respostas de Erro

  • Erro de validação de parâmetros:
{
  "content": [
    {
      "type": "text",
      "text": "❌ Erro ao enviar webhook!\n\n**Erro:** Erro de validação dos parâmetros\n\n**Detalhes:**\n{...}"
    }
  ],
  "isError": true
}
  • Erro HTTP (exemplo 500):
{
  "content": [
    {
      "type": "text",
      "text": "❌ Erro ao enviar webhook!\n\n**Erro:** Erro HTTP: Request failed with status code 500\n\n**Detalhes:**\n{...}"
    }
  ],
  "isError": true
}
  • URL não permitida (whitelist):
{
  "content": [
    {
      "type": "text",
      "text": "❌ URL não permitida pelo servidor (whitelist).\n\nConsulte o administrador para liberar o domínio ou URL desejada."
    }
  ],
  "isError": true
}

Validação de Headers HTTP

Alguns headers são validados automaticamente:

  • Authorization: deve ser no formato Bearer <token>
  • Content-Type: deve ser application/json, application/x-www-form-urlencoded ou application/xml

Exemplo de header válido:

{
  "headers": {
    "Authorization": "Bearer token123",
    "Content-Type": "application/json"
  }
}

Exemplo de header inválido:

{
  "headers": {
    "Authorization": "Token 123",
    "Content-Type": "text/plain"
  }
}

Próximos Passos

  1. Configure o Claude Desktop: Adicione a configuração no arquivo claude_desktop_config.json
  2. Reinicie o Claude Desktop: Para carregar a nova configuração
  3. Teste o MCP: Use o Claude para enviar webhooks com diferentes parâmetros

Exemplos Práticos

Veja o arquivo examples.json para exemplos detalhados de como usar o MCP em diferentes cenários:

  • Cadastro de usuários
  • Integrações com CRM
  • Notificações Slack
  • Processamento de pagamentos
  • E muito mais!

CLI Interativa

Você pode testar webhooks manualmente pelo terminal:

npx ts-node src/cli.ts

Siga os prompts para informar URL, método, parâmetros e headers.