Mailgun MCP Server

oficial

Interactúa con la API de Mailgun.

GitHub
56

Documentación

Servidor MCP de Mailgun

MCP

Descripción general

Un servidor del Protocolo de Contexto de Modelo (MCP) para Mailgun que proporciona a los agentes de IA una interfaz práctica y orientada a flujos de trabajo para enviar correos electrónicos, diagnosticar la entregabilidad y gestionar operaciones de la cuenta.

Nota: Este servidor MCP se ejecuta localmente en tu máquina. Mailgun no ofrece actualmente una versión alojada de este servidor.

Capacidades

  • Mensajería — Enviar correos electrónicos, recuperar mensajes almacenados, reenviar mensajes
  • Dominios — Ver detalles del dominio, verificar la configuración DNS, gestionar ajustes de seguimiento (clics, aperturas, cancelaciones de suscripción)
  • Webhooks — Listar, crear, actualizar y eliminar webhooks de eventos
  • Rutas — Ver y actualizar reglas de enrutamiento de correo entrante
  • Listas de correo — Crear y gestionar listas de correo y sus miembros
  • Plantillas — Crear y gestionar plantillas de correo electrónico con versionado
  • Analíticas — Consultar métricas de envío, métricas de uso y registros
  • Estadísticas — Ver estadísticas agregadas por dominio, etiqueta, proveedor, dispositivo y país
  • Supresiones — Ver rebotes, cancelaciones de suscripción, quejas y entradas de la lista de permitidos
  • IPs y grupos de IP — Ver asignaciones de IP y configuración de grupos de IP dedicados
  • Clasificación de rebotes — Analizar tipos de rebote y problemas de entrega

Requisitos previos

  • Node.js (v20.12 o superior)
  • Cuenta de Mailgun y clave API

Inicio rápido

Configuración

Añade lo siguiente a la configuración de tu cliente MCP:

{
  "mcpServers": {
    "mailgun": {
      "command": "npx",
      "args": ["-y", "@mailgun/mcp-server"],
      "env": {
        "MAILGUN_API_KEY": "YOUR-mailgun-api-key",
        "MAILGUN_API_REGION": "us"
      }
    }
  }
}

Variables de entorno

VariableRequeridoValor predeterminadoDescripción
MAILGUN_API_KEYSí—Tu clave API de Mailgun
MAILGUN_API_REGIONNousRegión API: us o eu
MAILGUN_MCP_TAGSNo(todas)Etiquetas de producto separadas por comas a habilitar. Equivalente a --tags. La bandera CLI tiene prioridad.

Filtrado por etiquetas

Puedes limitar qué herramientas registra el servidor a una o más etiquetas de producto de Mailgun. Esto es útil para acotar el conjunto de herramientas mostrado al modelo — por ejemplo, exponiendo solo herramientas de validación a un flujo de trabajo que no necesita capacidades de envío.

Etiquetas válidas: send, validate, optimize, inspect. Cuando no se especifica, se registran todas las herramientas (predeterminado actual).

El filtrado usa semántica OR: una herramienta se registra si alguna de sus etiquetas aparece en el conjunto activo.

Mediante bandera CLI — pasa --tags en el args de la configuración de tu cliente MCP:

{
  "mcpServers": {
    "mailgun": {
      "command": "npx",
      "args": ["-y", "@mailgun/mcp-server", "--tags", "validate,inspect"],
      "env": {
        "MAILGUN_API_KEY": "YOUR-mailgun-api-key"
      }
    }
  }
}

Mediante variable de entorno — establece MAILGUN_MCP_TAGS (la bandera CLI prevalece si ambas están presentes):

"env": {
  "MAILGUN_API_KEY": "YOUR-mailgun-api-key",
  "MAILGUN_MCP_TAGS": "validate,inspect"
}

Descubribilidad — ejecuta el binario con --list-tags para imprimir los valores de etiqueta soportados, o --help para el uso completo. Las etiquetas desconocidas se rechazan al inicio con un mensaje de error claro.

Rutas de configuración específicas del cliente

  • Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
  • Claude Desktop (Windows): %APPDATA%/Claude/claude_desktop_config.json
  • Claude Code: Ejecuta claude mcp add o edita ~/.claude.json

Ejemplos de prompts

Enviar un correo electrónico

Can you send an email to EMAIL_HERE with a funny email body that makes it sound
like it's from the IT Desk from Office Space? Please use the sending domain
DOMAIN_HERE, and make the email from "postmaster@DOMAIN_HERE"!

Nota: algunos clientes MCP requieren un plan de pago para invocar herramientas que envían datos. Si el envío falla silenciosamente, verifica el plan de tu cliente.

Obtener y visualizar estadísticas de envío

Would you be able to make a chart with email delivery statistics for the past week?

Gestionar plantillas

Create a welcome email template for new signups on my domain DOMAIN_HERE.
Include a personalized greeting and a call-to-action button.

Investigar la entregabilidad

Can you check the bounce classification stats for my account and tell me
what the most common bounce reasons are?

Solucionar problemas de DNS

Check the DNS verification status for my domain DOMAIN_HERE and tell me
if anything needs fixing.

Revisar supresiones

Are there any unsubscribes or complaints for DOMAIN_HERE? Summarize the
top offenders.

Gestionar reglas de enrutamiento

List all my inbound routes and explain what each one does.

Crear una lista de correo

Create a mailing list called announcements@DOMAIN_HERE and add these
members: [email protected], [email protected].

Comparar dominios

Compare my sending volume and delivery rates across all my domains for
the past month.

Interacción por región

Break down my email engagement by country and device for DOMAIN_HERE.

Revisar ajustes de seguimiento

List all my domains and show which ones have tracking enabled for clicks
and opens.

Desarrollo

Para ejecutar desde el código fuente, clona el repositorio y usa node directamente:

git clone https://github.com/mailgun/mailgun-mcp-server.git
cd mailgun-mcp-server
npm install
npm test

En la configuración de tu cliente MCP, reemplaza el comando npx con:

"command": "node",
"args": ["/path/to/mailgun-mcp-server/src/mailgun-mcp.js"]

Hooks de pre-commit

npm install instala un hook de pre-commit de git (mediante husky) que ejecuta oxlint --fix y oxfmt en los archivos TypeScript/JavaScript preparados y ejecuta npm run check:versions. Los problemas solucionables se corrigen automáticamente y se vuelven a preparar; los commits que introducen errores de lint no solucionables o discrepancias de sincronización de versión son rechazados. Si ya tenías un clon local antes de este cambio, ejecuta npm install una vez para instalar el hook.

Nota sobre añadir endpoints

Al añadir un nuevo endpoint, si usas una cadena simple para su definición, se etiquetará por defecto con el tipo de producto send en el campo _meta. Si deseas etiquetarlo como un producto diferente, usa la versión de objeto del tipo EndpointEntry.

Consideraciones de seguridad

Aislamiento de la clave API

Tu clave API de Mailgun se pasa como una variable de entorno y nunca se expone al modelo de IA en sí — solo la utiliza el proceso del servidor MCP para autenticar las solicitudes. El servidor no registra claves API, parámetros de solicitud ni datos de respuesta.

Ejecución local

El servidor se ejecuta localmente en tu máquina. Toda la comunicación con la API de Mailgun se realiza a través de HTTPS con validación de certificado TLS aplicada. No se envían datos a servicios de terceros más allá de la API de Mailgun.

Permisos de la clave API

Usa una clave API de Mailgun dedicada con permisos limitados únicamente a las operaciones que necesites. El servidor expone operaciones de lectura y actualización, pero no expone ninguna operación de eliminación, lo que limita el alcance de acciones no deseadas.

Limitación de tasa

El servidor no implementa limitación de tasa del lado del cliente. Cada llamada de herramienta desde la IA se traduce directamente en una solicitud a la API de Mailgun. El servidor confía en los límites de tasa del lado del servidor de Mailgun para prevenir abusos — las solicitudes que excedan esos límites devolverán un error al asistente de IA.

Inyección de prompts

Como con cualquier servidor MCP, un prompt manipulado o adversario podría engañar al asistente de IA para que realice operaciones que no pretendías — por ejemplo, modificar ajustes de seguimiento o leer miembros de listas de correo. Revisa las confirmaciones de llamadas de herramientas de tu asistente de IA antes de aprobar acciones, especialmente en contextos de prompts no confiables.

URLs de webhooks

Las operaciones de creación y actualización de webhooks aceptan URLs arbitrarias proporcionadas a través del asistente de IA. El servidor MCP pasa estas URLs a la API de Mailgun sin validación adicional. Mailgun es responsable de validar los destinos de los webhooks. Asegúrate de que tu asistente de IA no establezca URLs de webhooks en direcciones internas o sensibles no deseadas.

Validación de entrada

Todos los parámetros de las herramientas se validan contra la especificación OpenAPI de Mailgun utilizando esquemas Zod. Sin embargo, la validación depende de la precisión de la especificación OpenAPI, y algunos parámetros de casos límite pueden recurrir a una validación permisiva. La API de Mailgun realiza su propia validación del lado del servidor como una capa adicional de protección.

Depuración

El servidor MCP se comunica a través de stdio. Consulta la Guía de depuración de MCP para solucionar problemas.

Licencia

Apache 2.0 — consulta LICENSE para más detalles.

Contribuciones

¡Agradecemos las contribuciones! No dudes en enviar un Pull Request o abrir un Issue.