Mailgun

Servidor MCP de Mailgun

Descripción general

Un servidor de Model Context Protocol (MCP) para Mailgun que ofrece 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.

[!NOTE] Este servidor MCP se ejecuta localmente en tu máquina y se comunica mediante stdio. Mailgun no ofrece actualmente una versión alojada de este servidor.

Capacidades

• Mensajería — Enviar correos electrónicos, recuperar mensajes almacenados y volver a enviarlos
• Dominios — Consultar detalles de dominios, verificar la configuración de DNS y gestionar los ajustes de seguimiento (clics, aperturas, cancelaciones de suscripción)
• Webhooks — Enumerar, crear y actualizar webhooks de eventos
• Rutas — Consultar y actualizar reglas de enrutamiento de correo entrante
• Listas de correo — Crear, consultar y actualizar listas de correo y sus miembros
• Plantillas — Crear, consultar y actualizar plantillas de correo electrónico con control de versiones
• Analítica — Consultar métricas de envío, métricas de uso y registros
• Estadísticas — Consultar estadísticas agregadas por dominio, etiqueta, proveedor, dispositivo y país
• Supresiones — Consultar rebotes, cancelaciones de suscripción, quejas y entradas de la lista de permitidos
• IP y grupos de IP — Consultar asignaciones de IP y la configuración de grupos de IP dedicadas
• Clasificación de rebotes — Analizar tipos de rebote y problemas de entrega
• Validación — Validar la entregabilidad y la sintaxis de direcciones de correo electrónico antes del envío (validate)
• Optimize (ubicación en la bandeja de entrada) — Recuperar resultados de pruebas de ubicación en la bandeja de entrada / pruebas con direcciones semilla para evaluar la entregabilidad (optimize)
• Inspect (vista previa del correo electrónico) — Recuperar resultados de pruebas de renderizado y vista previa del correo electrónico en distintos clientes (inspect)
• Límites de la cuenta — Consultar los límites mensuales de envío personalizados

Las etiquetas anteriores (validate, optimize, inspect) son las etiquetas de producto que utiliza el filtrado por etiquetas. Todas las demás capacidades se registran bajo la etiqueta send, que se divide en send.<group> conjuntos de herramientas.

[!NOTE] Las herramientas se limitan a operaciones de lectura y actualización: no se exponen operaciones de eliminación, lo que reduce el impacto de una acción no deseada. Consulta Consideraciones de seguridad.

Cómo funciona

El servidor se basa en OpenAPI. Al iniciarse, analiza una especificación de OpenAPI de Mailgun incluida y registra una lista permitida seleccionada de endpoints como herramientas MCP, generando el esquema de entrada de cada herramienta (mediante Zod) a partir de la especificación. Cada herramienta lleva anotada una etiqueta de producto de Mailgun (send, validate, optimize o inspect), el conjunto de herramientas al que pertenece y si solo lee datos.

De forma predeterminada, el servidor carga todas las herramientas al iniciarse. Con --tags dynamic, carga un pequeño conjunto básico de herramientas más tres herramientas que el modelo utiliza para cargar otros conjuntos de herramientas cuando los necesita, lo que mantiene pequeñas las definiciones de herramientas que se envían al modelo. El filtrado por etiquetas carga en su lugar un conjunto fijo de herramientas al iniciarse, de modo que un flujo de trabajo determinado pueda exponer exactamente los productos que necesita.

Requisitos previos

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

Instalación

El servidor se publica en npm como @mailgun/mcp-server y se ejecuta mediante stdio. La mayoría de los clientes pueden iniciarlo cuando lo necesitan con npx, así que no hace falta instalar nada globalmente. En cada fragmento siguiente, sustituye YOUR-mailgun-api-key por una clave de tus ajustes de seguridad de la API de Mailgun.

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

Claude Code

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

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

Claude Desktop

Abre Settings → Developer → Edit Config o edita 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

Abre la paleta de comandos y selecciona Cursor Settings → MCP → Add new global MCP server; luego añade:

{
  "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)

Añade lo siguiente a tu 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

Añádelo 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	Obligatoria	Valor predeterminado	Descripción
MAILGUN_API_KEY	Sí	—	Tu clave de API de Mailgun
MAILGUN_API_REGION	No	us	Región de la API: us o eu
MAILGUN_API_HOSTNAME	No	(derivado de la región)	Anula el nombre de host de la API (p. ej., api.eu.mailgun.net). Tiene prioridad sobre la región.
MAILGUN_MCP_TAGS	No	(todas)	Etiquetas o conjuntos de herramientas separados por comas que se cargarán, o dynamic para las herramientas básicas y cargar otras cuando se necesiten. Equivale a --tags. La opción de CLI tiene prioridad.

Opciones de CLI

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

Opción	Descripción
--tags <list>	Etiquetas o conjuntos de herramientas separados por comas que se cargarán (predeterminado: todas). Valores válidos: all, dynamic, core, send, validate, optimize, inspect y los conjuntos de herramientas send.<group>.
--list-tags	Imprime todos los valores válidos de --tags con una descripción y termina.
--help, -h	Muestra el uso y termina.

Conjuntos de herramientas bajo demanda

Con --tags dynamic (o MAILGUN_MCP_TAGS=dynamic), el servidor se inicia con estas herramientas básicas:

Herramienta	Función
post-v3-domain-messages	Enviar un correo electrónico
get-v4-domains	Enumerar dominios
get-v4-domains-name	Detalles del dominio y registros DNS
put-v4-domains-name-verify	Volver a comprobar los registros DNS de un dominio
get-v3-domains-name-tracking	Ajustes de seguimiento
get_metrics_summary	Resumen de las métricas de envío principales
post-v1-analytics-metrics	Consultar métricas de la cuenta
post-v1-analytics-logs	Consultar registros de eventos
post-v2-bounce-classification-metrics	Métricas de clasificación de rebotes
get-v3-domain-bounces	Enumerar rebotes
get-v3-domain-bounces-address	Buscar un registro de rebote
get-v3-domain-unsubscribes	Enumerar cancelaciones de suscripción
get-v3-domain-complaints	Enumerar quejas
get-v3-domain-templates	Enumerar plantillas
validate_email	Validar una dirección de correo electrónico

Cada herramienta pertenece a un conjunto de herramientas. El modelo carga el resto de un conjunto cuando una tarea lo necesita:

Conjunto de herramientas	Herramientas	Contenido
send.messages	3	Enviar correos electrónicos; recuperar y volver a enviar mensajes almacenados
send.domains	8	Dominios, verificación de DNS, colas de envío, ajustes de seguimiento
send.webhooks	4	Webhooks de dominio
send.account	8	IP de la cuenta, grupos de IP dedicadas, límites de envío personalizados
send.message_tags	8	Etiquetas de mensajes, estadísticas por etiqueta, límites de etiquetas
send.analytics	12	Estadísticas y agregados, métricas y registros de analítica, clasificación de rebotes
send.suppressions	8	Rebotes, cancelaciones de suscripción, quejas, lista de permitidos
send.routes	3	Rutas de entrada
send.lists	8	Listas de correo y miembros
send.templates	8	Plantillas y versiones de plantillas
validate	1	Validación de direcciones de correo electrónico
optimize	1	Resultados de pruebas de ubicación en la bandeja de entrada
inspect	1	Resultados de pruebas de vista previa del correo electrónico

El modelo carga conjuntos de herramientas mediante tres herramientas adicionales:

• mailgun_list_toolsets enumera todos los conjuntos de herramientas y sus herramientas, e indica cuáles están cargadas y cuáles modifican datos. Si se le proporciona el nombre de una herramienta, devuelve en su lugar el esquema de entrada de esa herramienta.
• mailgun_enable_toolset carga uno o varios conjuntos de herramientas. A continuación, el servidor notifica al cliente que la lista de herramientas ha cambiado (notifications/tools/list_changed), y las nuevas herramientas aparecen junto a las básicas. La respuesta enumera las nuevas herramientas sin sus esquemas de entrada, que se incluyen en la lista de herramientas actualizada.
• mailgun_call_tool ejecuta una herramienta de solo lectura por nombre, esté cargado o no su conjunto de herramientas. Es una alternativa para los clientes que no actualizan su lista de herramientas tras un cambio. Rechaza las herramientas básicas y las que modifican datos, por lo que estas siempre se ejecutan como llamadas a herramientas independientes.

Los conjuntos de herramientas cargados permanecen disponibles hasta que el cliente se desconecta. La carga bajo demanda requiere un cliente que actualice su lista de herramientas cuando el servidor informa de un cambio; Claude Code lo hace. En los clientes que no lo hacen, las herramientas recién cargadas no aparecerán: las herramientas de solo lectura seguirán funcionando mediante mailgun_call_tool, y las herramientas que modifican datos requieren la configuración predeterminada (todas las herramientas) o --tags, por ejemplo, --tags core,send.templates.

Filtrado por etiquetas

Si se establece --tags o MAILGUN_MCP_TAGS en cualquier valor distinto de dynamic, se cargarán exactamente las herramientas coincidentes al iniciarse, sin las herramientas de carga. Úsalo para limitar las herramientas que se muestran al modelo (por ejemplo, solo las herramientas de validación para un flujo de trabajo que no envía correos electrónicos).

Valores válidos (ejecuta --list-tags para ver las descripciones):

• all — todas las herramientas (valor predeterminado)
• dynamic — las herramientas básicas, con otros conjuntos de herramientas cargados bajo demanda. Úsalo por sí solo; combinarlo con otros valores provoca un error al iniciarse.
• core — solo las herramientas básicas enumeradas arriba
• send, validate, optimize, inspect — todas las herramientas de ese producto (send incluye todos los conjuntos de herramientas send.<group>)
• Un ID de conjunto de herramientas, como send.templates

El filtrado utiliza semántica OR: se carga una herramienta si coincide con cualquiera de los valores de la lista. Por ejemplo, core,send.templates carga las herramientas básicas y todas las herramientas de plantillas.

Mediante la opción de CLI — pasa --tags en 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 una variable de entorno — establece MAILGUN_MCP_TAGS (la opción de CLI tiene prioridad si se especifican ambas):

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

[!TIP] Ejecuta el binario con --list-tags para imprimir todos los valores válidos, o con --help para ver el uso completo. Los valores desconocidos se rechazan al iniciarse con un mensaje de error claro.

Ejemplos de instrucciones

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 sin mostrar ningún error, comprueba 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?

Administrar 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 las supresiones

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

Administrar 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.

Comprobar la ubicación en la bandeja de entrada (Optimize)

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 (Inspect)

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. Clona, instala, compila y prueba:

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/ en dist/ y copia la especificación OpenAPI incluida. Configura tu cliente MCP para que apunte a la entrada compilada en lugar de a npx (usa 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 editas

Los servidores MCP son procesos stdio de larga duración que no se recargan automáticamente, así que el ciclo es: recompilar al guardar y, después, volver a conectar el cliente para aplicar los cambios.

1. Ejecuta npm run build una vez para que dist/openapi.yaml esté disponible.

2. Mantén en ejecución el compilador de TypeScript para recompilar dist/ cada vez que guardes:

   npx tsc --watch
   

3. Configura un cliente MCP independiente (o MCP Inspector, más abajo) para que apunte a dist/mailgun-mcp.js. Después de un cambio, reinicia la sesión del cliente MCP para cargar la nueva compilación.

Probar con MCP Inspector

MCP Inspector te permite probar herramientas sin un cliente completo. Primero compila y, después, ejecútalo con el servidor compilado:

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

Abre la interfaz de Inspector, haz clic en Connect y, después, usa List Tools para verificar que el servidor funciona. Para probar un conjunto de herramientas filtrado, añade indicadores 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 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 que se puedan corregir se corrigen automáticamente y se vuelven a preparar; se rechazan las confirmaciones que introduzcan errores de lint no corregibles o discrepancias de sincronización de versiones. Si ya tenías un clon local antes de este cambio, ejecuta npm install una vez para instalar el hook.

Nota sobre cómo añadir endpoints

Los endpoints se agrupan por conjunto de herramientas en endpointGroups. Una entrada de cadena simple toma su etiqueta de producto del conjunto de herramientas (send.templates → send) y se considera de solo lectura únicamente si es un GET. Usa el formato de objeto de EndpointEntry para establecer un nombre de herramienta, marcar una herramienta como core (se carga al inicio en modo dinámico) o marcar como readOnly: true un POST que solo consulta datos.

Consideraciones de seguridad

Aislamiento de la clave de API

La clave de API de Mailgun se pasa como variable de entorno y nunca se expone al modelo de IA; solo la usa el proceso del servidor MCP para autenticar las solicitudes. El servidor no registra las claves de API, los parámetros de las solicitudes ni los datos de las respuestas.

Ejecución local

El servidor se ejecuta localmente en tu máquina. Toda la comunicación con la API de Mailgun se realiza mediante HTTPS, con la validación de certificados TLS obligatoria. No se envían datos a servicios de terceros aparte de la API de Mailgun.

Permisos de la clave de API

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

Limitación de velocidad

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

Inyección de prompts

Como ocurre con cualquier servidor MCP, un prompt manipulado o malicioso podría engañar al asistente de IA para que invoque operaciones que no pretendías, por ejemplo, modificar la configuración de seguimiento o leer los miembros de una lista de correo. Revisa las confirmaciones de llamadas a herramientas de tu asistente de IA antes de aprobar acciones, especialmente en contextos con prompts que no sean de confianza.

Carga y aprobación de herramientas

Todas las herramientas incluyen la anotación MCP readOnlyHint, por lo que los clientes pueden distinguir las herramientas que solo leen datos de las que los modifican (por ejemplo, al solicitar aprobación). mailgun_list_toolsets y mailgun_call_tool son de solo lectura. mailgun_enable_toolset cambia las herramientas que ve la sesión, por lo que no está marcado como de solo lectura, pero nunca modifica nada en Mailgun. mailgun_call_tool ejecuta únicamente herramientas de solo lectura que no forman parte del conjunto principal, por lo que aprobarlo nunca puede enviar correos electrónicos ni cambiar la configuración de la cuenta. Las herramientas que modifican datos siempre se ejecutan como llamadas independientes.

Cargar conjuntos de herramientas bajo demanda reduce lo que ve el modelo; no es un control de acceso, porque el modelo puede cargar cualquier conjunto de herramientas. Para limitar las herramientas que expone el servidor, usa --tags.

URL de webhooks

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

Validación de entradas

Todos los parámetros de las herramientas se validan con esquemas de Zod basados en la especificación OpenAPI de Mailgun. 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 capa de protección adicional.

Depuración

El servidor MCP se comunica mediante stdio. Consulta la guía de depuración de MCP para solucionar problemas.

Licencia

Apache 2.0 — consulta LICENSE para obtener más información.

Contribuciones

¡Agradecemos las contribuciones! No dudes en enviar una solicitud de incorporación de cambios o abrir un problema.