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

As dependências já estão instaladas. Para reinstalar se necessário:

cd webhooks-mcp
npm install

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"
  }
}

FAQ

Como configuro domínios permitidos?

Defina a variável de ambiente WHITELIST_URLS com uma lista separada por vírgula dos domínios ou URLs permitidos.

Como habilito logs mais detalhados?

Defina LOG_LEVEL=debug para ver logs detalhados.

Como habilito retentativas automáticas?

Defina RETRY_ATTEMPTS e RETRY_BASE_DELAY_MS conforme desejado.

Como executo os testes automatizados?

Basta rodar npm test na raiz do projeto.

Como reportar um bug ou sugerir melhoria?

Abra uma issue no repositório do GitHub.

Próximos Passos

Configure o Claude Desktop: Adicione a configuração no arquivo claude_desktop_config.json
Reinicie o Claude Desktop: Para carregar a nova configuração
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!

Deploy com Docker

Você pode rodar o MCP facilmente usando Docker:

docker build -t webhook-mcp .
docker run --rm -p 3000:3000 \
  -e WHITELIST_URLS="api.exemplo.com" \
  -e LOG_LEVEL=info \
  -e RETRY_ATTEMPTS=3 \
  webhook-mcp

Adapte as variáveis de ambiente conforme necessário.

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.