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

2. 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": "[email protected]",
    "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

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!

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.