Mailgun

Servidor MCP de Mailgun

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 las operaciones de la cuenta.

[!NOTE] Este servidor MCP se ejecuta localmente en su máquina y se comunica a través de stdio. 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 la configuración de seguimiento (clics, aperturas, cancelaciones de suscripción)
• Webhooks — Listar, crear y actualizar webhooks de eventos
• Rutas — Ver y actualizar reglas de enrutamiento de correo entrante
• Listas de correo — Crear, ver y actualizar listas de correo y sus miembros
• Plantillas — Crear, ver y actualizar 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 IPs — Ver asignaciones de IP y configuración de grupos de IPs dedicadas
• Clasificación de rebotes — Analizar tipos de rebote y problemas de entrega
• Validación — Validar la entregabilidad y sintaxis de direcciones de correo electrónico antes del envío (validate)
• Optimizar (Ubicación en la bandeja de entrada) — Recuperar resultados de pruebas de ubicación en bandeja de entrada / seed para medir la entregabilidad (optimize)
• Inspeccionar (Vista previa de correo electrónico) — Recuperar resultados de pruebas de renderizado y vista previa de correo electrónico en diferentes clientes (inspect)
• Límites de cuenta — Ver límites de envío mensuales personalizados

Las etiquetas entre paréntesis anteriores (validate, optimize, inspect) son las etiquetas de producto utilizadas por el filtrado de etiquetas. Todas las demás capacidades se registran bajo la etiqueta send.

[!NOTE] Las herramientas se limitan a operaciones de lectura y actualización — no se exponen operaciones de eliminación, lo que mantiene pequeño el radio de acción de una acción no deseada. Consulte Consideraciones de seguridad.

Cómo funciona

El servidor está impulsado por OpenAPI. Al iniciarse, analiza una especificación OpenAPI de Mailgun incluida y registra una lista blanca curada de endpoints como herramientas MCP, generando el esquema de entrada de cada herramienta (a través de Zod) a partir de la especificación. Cada herramienta se anota con una etiqueta de producto de Mailgun (send, validate, optimize o inspect). Todas las herramientas coincidentes se registran por adelantado — no hay carga diferida o bajo demanda. El filtrado de etiquetas se aplica al inicio para delimitar qué herramientas se registran, de modo que un flujo de trabajo determinado pueda exponer solo los productos que necesita.

Requisitos previos

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

Instalación

El servidor se publica en npm como @mailgun/mcp-server y se ejecuta sobre stdio. La mayoría de los clientes pueden iniciarlo bajo demanda con npx, por lo que no hay nada que instalar globalmente. En cada fragmento a continuación, reemplace YOUR-mailgun-api-key con una clave de su configuración de seguridad de la API de Mailgun.

[!TIP] Si su cuenta está alojada en la región UE de Mailgun, agregue "MAILGUN_API_REGION": "eu" al bloque env (o -e MAILGUN_API_REGION=eu en la CLI). Su valor predeterminado es us.

Claude Code

claude mcp add mailgun -e MAILGUN_API_KEY=YOUR-mailgun-api-key -- npx -y @mailgun/mcp-server

Luego ejecute /mcp en Claude Code para confirmar que el servidor mailgun está conectado.

Claude Desktop

Abra Configuración → Desarrollador → Editar configuración, o edite el archivo directamente:

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

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

Cursor

Abra la paleta de comandos y elija Configuración de Cursor → MCP → Agregar nuevo servidor MCP global, luego agregue:

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

Codex

codex mcp add mailgun \
  --env MAILGUN_API_KEY=YOUR-mailgun-api-key \
  -- npx -y @mailgun/mcp-server

VS Code (GitHub Copilot)

Agregue lo siguiente a su settings.json:

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

Windsurf

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

Gemini CLI

Agregar a ~/.gemini/settings.json:

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

Configuración

Variables de entorno

Variable	Requerido	Predeterminado	Descripción
MAILGUN_API_KEY	Sí	—	Su clave API de Mailgun
MAILGUN_API_REGION	No	us	Región API: us o eu
MAILGUN_API_HOSTNAME	No	(derivado de la región)	Anula el nombre de host de la API (ej. api.eu.mailgun.net). Tiene prioridad sobre la región.
MAILGUN_MCP_TAGS	No	(todas)	Etiquetas de producto separadas por comas para habilitar. Equivalente a --tags. La bandera CLI tiene prioridad.

Opciones de CLI

Pase las banderas después del nombre del paquete en el args de su cliente (ej. ["-y", "@mailgun/mcp-server", "--tags", "validate,inspect"]).

Bandera	Descripción
--tags <list>	Etiquetas de producto separadas por comas para habilitar (predeterminado: todas). Válidas: send, validate, optimize, inspect.
--list-tags	Imprime los valores de etiqueta válidos y sale.
--help, -h	Muestra el uso y sale.

Filtrado de etiquetas

Puede limitar qué herramientas registra el servidor a una o más etiquetas de producto de Mailgun. Esto es útil para reducir 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 registra cada herramienta (predeterminado actual).

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

Mediante bandera CLI — pase --tags en el args de la configuración de su 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 — establezca MAILGUN_MCP_TAGS (la bandera CLI gana si ambas están presentes):

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

[!TIP] Ejecute el binario con --list-tags para imprimir los valores de etiqueta admitidos, o --help para el uso completo. Las etiquetas desconocidas se rechazan al inicio con un mensaje de error claro.

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

[!NOTE] Algunos clientes MCP requieren un plan de pago para invocar herramientas que envían datos. Si el envío falla silenciosamente, verifique el plan de su 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: alice@example.com, bob@example.com.

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 la configuración de seguimiento

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

Validar una dirección de correo electrónico

Validate the email address EMAIL_HERE and tell me whether it's safe to send to.

Verificar la ubicación en la bandeja de entrada (Optimizar)

Pull the inbox placement results for seed test RESULT_ID_HERE and summarize
where my message landed (inbox, spam, or missing) by provider.

Previsualizar un correo electrónico (Inspeccionar)

Get the email preview results for test TEST_ID_HERE and tell me if the email
renders correctly across clients.

Desarrollo

Ejecutar desde el código fuente

El servidor está escrito en TypeScript. Clone, instale, compile y pruebe:

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

npm run build compila src/ a dist/ y copia la especificación OpenAPI incluida. Apunte su cliente MCP a la entrada compilada en lugar de npx (use una ruta absoluta):

{
  "mcpServers": {
    "mailgun": {
      "command": "node",
      "args": ["/absolute/path/to/mailgun-mcp-server/dist/mailgun-mcp.js"],
      "env": {
        "MAILGUN_API_KEY": "YOUR-mailgun-api-key"
      }
    }
  }
}

Pruebas en vivo mientras edita

Los servidores MCP son procesos stdio de larga duración que no se recargan en caliente, por lo que el ciclo es: recompilar al guardar, luego reconectar el cliente para recoger los cambios.

1. Ejecute npm run build una vez para que dist/openapi.yaml esté en su lugar.

2. Mantenga el compilador de TypeScript ejecutándose para recompilar dist/ en cada guardado:

   npx tsc --watch
   

3. Apunte un cliente MCP separado (o el Inspector MCP, a continuación) a dist/mailgun-mcp.js. Después de un cambio, reinicie la sesión del cliente MCP para cargar la nueva compilación.

Pruebas con el Inspector MCP

El Inspector MCP le permite ejercitar las herramientas sin un cliente completo. Compile primero, luego ejecútelo contra el servidor compilado:

npm run build
MAILGUN_API_KEY=YOUR-mailgun-api-key npx @modelcontextprotocol/inspector node dist/mailgun-mcp.js

Abra la interfaz de usuario del Inspector, haga clic en Conectar, luego use Listar herramientas para verificar que el servidor está funcionando. Para probar un conjunto de herramientas filtrado, agregue banderas después de la ruta del servidor:

MAILGUN_API_KEY=YOUR-mailgun-api-key npx @modelcontextprotocol/inspector node dist/mailgun-mcp.js --tags validate,inspect

Hooks de pre-commit

npm install instala un hook git pre-commit (a través de 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 en la sincronización de versiones son rechazados. Si ya tenía un clon local antes de este cambio, ejecute npm install una vez para instalar el hook.

Nota sobre la adición de endpoints

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

Consideraciones de seguridad

Aislamiento de la clave API

Su 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 su 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

Utilice una clave API de Mailgun dedicada con permisos limitados únicamente a las operaciones que necesite. El servidor expone operaciones de lectura y actualización, pero no expone ninguna operación de eliminación, lo que limita el radio de acción 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 no deseadas — por ejemplo, modificar la configuración de seguimiento o leer miembros de listas de correo. Revise las confirmaciones de llamadas de herramientas de su 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úrese de que su asistente de IA no establezca URLs de webhook 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 extremos 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. Consulte la Guía de depuración de MCP para la solución de problemas.

Licencia

Apache 2.0 — consulte LICENSE para más detalles.

Contribuciones

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