Webhooks MCP

Envía solicitudes HTTP a webhooks con parámetros dinámicos.

GitHubPrueba este MCPPatrocinado

Documentación

Webhooks MCP

Testes Automatizados

Un servidor MCP (Model Context Protocol) para enviar solicitudes HTTP a webhooks con parámetros dinámicos.

Funcionalidades

  • ✅ Soporte para todos los métodos HTTP: GET, POST, PUT, PATCH, DELETE
  • ✅ Parámetros dinámicos de cualquier tipo (nombre, correo electrónico, teléfono, etc.)
  • ✅ Headers HTTP personalizados
  • ✅ Timeout configurable
  • ✅ Validación de entrada con Zod
  • ✅ Manejo de errores detallado
  • ✅ Registros de solicitud y respuesta

Instalación

  1. Las dependencias ya están instaladas. Para reinstalarlas si es necesario:
cd webhooks-mcp
npm install
  1. Compile el TypeScript:
npm run build

Configuración en Claude Desktop

Agregue la siguiente configuración en el archivo claude_desktop_config.json:

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

Ubicación del archivo de configuración:

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

Uso

Herramienta Disponible

send_webhook

Envía una solicitud HTTP a un webhook con parámetros personalizados.

Parámetros:

  • url (obligatorio): URL del webhook (ej: https://meuwebhook.com.br)
  • method (obligatorio): Método HTTP (GET, POST, PUT, PATCH, DELETE)
  • parameters (opcional): Objeto con parámetros de cualquier tipo
  • headers (opcional): Headers HTTP adicionales
  • timeout (opcional): Timeout en milisegundos (predeterminado: 30000)

Ejemplos de Uso

1. POST con datos de usuario

{
  "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 con parámetros de consulta

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

3. PUT con 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 simple

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

Comportamiento por Método HTTP

  • GET/DELETE: Los parámetros se envían como parámetros de consulta en la URL
  • POST/PUT/PATCH: Los parámetros se envían en el cuerpo de la solicitud como JSON

Manejo de Errores

El MCP maneja diferentes tipos de errores:

  • Errores de validación: Cuando los parámetros no tienen el formato correcto
  • Errores HTTP: Cuando el webhook devuelve un estado de error (4xx, 5xx)
  • Errores de red: Timeout, conexión rechazada, etc.

Desarrollo

Scripts disponibles

  • npm run build: Compila el TypeScript
  • npm run dev: Compila en modo watch
  • npm start: Ejecuta el servidor compilado

Estructura del proyecto

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

Probando el Servidor

Para probar si el 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.

Registros

El servidor genera registros detallados:

  • Solicitudes enviadas (método, URL, parámetros)
  • Respuestas recibidas (estado, tiempo de respuesta)
  • Errores detallados con contexto

Seguridad

  • Validación rigurosa de entrada con Zod
  • Headers de User-Agent que identifican el MCP
  • Timeout configurable para evitar solicitudes infinitas
  • Manejo seguro de errores sin exposición de datos sensibles
  • Lista blanca de URLs/dominios: configure la variable de entorno WHITELIST_URLS (separada por comas) para restringir los destinos permitidos. Ejemplo:
export WHITELIST_URLS="api.exemplo.com,https://hooks.slack.com"

Si no se configura, se permitirá cualquier URL.

  • Niveles de registro configurables: defina la variable de entorno LOG_LEVEL para controlar la verbosidad de los registros (debug, info, warn, error). Ejemplo:
export LOG_LEVEL="debug"
  • Reintentos automáticos: defina las variables de entorno RETRY_ATTEMPTS (número de intentos, predeterminado 1) y RETRY_BASE_DELAY_MS (retraso inicial en ms, predeterminado 500) para habilitar reintentos automáticos con retroceso exponencial en fallos temporales.
export RETRY_ATTEMPTS=3
export RETRY_BASE_DELAY_MS=1000
  • Internacionalización (i18n): defina la variable de entorno LANG como pt (predeterminado) o en para recibir mensajes en portugués o inglés.
export LANG=en

Ejemplos de Respuestas de Error

  • Error de validación 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
}
  • Error HTTP (ejemplo 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 no permitida (lista blanca):
{
  "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
}

Validación de Headers HTTP

Algunos headers se validan automáticamente:

  • Authorization: debe tener el formato Bearer <token>
  • Content-Type: debe ser application/json, application/x-www-form-urlencoded o application/xml

Ejemplo de header válido:

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

Ejemplo de header inválido:

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

Preguntas Frecuentes

¿Cómo configuro dominios permitidos?

Defina la variable de entorno WHITELIST_URLS con una lista separada por comas de los dominios o URLs permitidos.

¿Cómo habilito registros más detallados?

Defina LOG_LEVEL=debug para ver registros detallados.

¿Cómo habilito reintentos automáticos?

Defina RETRY_ATTEMPTS y RETRY_BASE_DELAY_MS según lo deseado.

¿Cómo ejecuto las pruebas automatizadas?

Simplemente ejecute npm test en la raíz del proyecto.

¿Cómo reporto un error o sugiero una mejora?

Abra un issue en el repositorio de GitHub.

Próximos Pasos

  1. Configure Claude Desktop: Agregue la configuración en el archivo claude_desktop_config.json
  2. Reinicie Claude Desktop: Para cargar la nueva configuración
  3. Pruebe el MCP: Use Claude para enviar webhooks con diferentes parámetros

Ejemplos Prácticos

Consulte el archivo examples.json para ver ejemplos detallados de cómo usar el MCP en diferentes escenarios:

  • Registro de usuarios
  • Integraciones con CRM
  • Notificaciones de Slack
  • Procesamiento de pagos
  • ¡Y mucho más!

Despliegue con Docker

Puede ejecutar el MCP fácilmente 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 las variables de entorno según sea necesario.

CLI Interactiva

Puede probar webhooks manualmente desde la terminal:

npx ts-node src/cli.ts

Siga las indicaciones para proporcionar URL, método, parámetros y headers.