Mailtrap

Servidor MCP de Mailtrap

Un servidor MCP que proporciona herramientas para enviar y probar en sandbox mediante Mailtrap.

Requisitos previos

Antes de usar este servidor MCP, necesitas:

1. Crear una cuenta de Mailtrap
2. Verificar tu dominio
3. Obtener tu token de API desde Configuración de API de Mailtrap
4. Obtener tu ID de cuenta desde Gestión de cuentas de Mailtrap

Variables de entorno requeridas:

• MAILTRAP_API_TOKEN - Requerido para toda la funcionalidad
• MAILTRAP_ACCOUNT_ID - Requerido para plantillas, estadísticas, registros de correo, listado/visualización de sandbox y dominios de envío. Opcional solo para las herramientas de envío (send-email, send-sandbox-email y las herramientas batch-send-*).

Opcional (se puede pasar como parámetros de la herramienta en su lugar):

• DEFAULT_FROM_EMAIL - Correo electrónico del remitente predeterminado cuando from no se proporciona a send-email, send-sandbox-email o las herramientas batch-send-* (donde completa base.from). Permite cambiar el remitente en cada llamada mediante el parámetro from.
• MAILTRAP_SANDBOX_ID - ID de sandbox predeterminado para las herramientas de sandbox cuando no se proporciona sandbox_id. Permite cambiar entre sandboxes en cada llamada mediante el parámetro sandbox_id.
• MAILTRAP_TEST_INBOX_ID - ID de bandeja de entrada de prueba predeterminado para las herramientas de sandbox cuando no se proporciona test_inbox_id. Permite cambiar entre bandejas de entrada en cada llamada mediante el parámetro test_inbox_id. Alias heredado de MAILTRAP_SANDBOX_ID, que aún se respeta como alternativa.
• MAILTRAP_ORGANIZATION_ID - Requerido para las herramientas de organización (list-sub-accounts, create-sub-account).
• MAILTRAP_ORGANIZATION_API_TOKEN - Token de API con alcance de organización. Requerido para las herramientas de organización (separado de MAILTRAP_API_TOKEN).

Instalación rápida

CLI de Smithery

Smithery es un instalador y administrador de registros para servidores MCP que funciona con todos los clientes de IA.

npx @smithery/cli install mailtrap

Smithery maneja automáticamente la configuración del cliente y proporciona un proceso de configuración interactivo. Es la forma más fácil de comenzar con servidores MCP localmente.

Configuración

Claude Desktop

Usa MCPB para instalar el servidor de Mailtrap. Puedes encontrar esos archivos en Releases.
Descarga el archivo .MCPB y ábrelo. Si tienes Claude Desktop, se abrirá y sugerirá configurarlo.

Claude Desktop o Cursor

Agrega la siguiente configuración:

{
  "mcpServers": {
    "mailtrap": {
      "command": "npx",
      "args": ["-y", "mcp-mailtrap"],
      "env": {
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "your_sender@example.com",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

Si usas asdf para administrar Node.js, debes usar la ruta absoluta al ejecutable (ejemplo para Mac)

{
  "mcpServers": {
    "mailtrap": {
      "command": "/Users/<username>/.asdf/shims/npx",
      "args": ["-y", "mcp-mailtrap"],
      "env": {
        "PATH": "/Users/<username>/.asdf/shims:/usr/bin:/bin",
        "ASDF_DIR": "/opt/homebrew/opt/asdf/libexec",
        "ASDF_DATA_DIR": "/Users/<username>/.asdf",
        "ASDF_NODEJS_VERSION": "20.6.1",
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "your_sender@example.com",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

Ubicación del archivo de configuración de Claude Desktop

Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Ubicación del archivo de configuración de Cursor

Mac: ~/.cursor/mcp.json

Windows: %USERPROFILE%\.cursor\mcp.json

VS Code

Cambio manual de configuración

Ejecuta en la Paleta de comandos: Preferences: Open User Settings (JSON)

Luego, en el archivo de configuración, agrega la siguiente configuración:

{
  "mcp": {
    "servers": {
      "mailtrap": {
        "command": "npx",
        "args": ["-y", "mcp-mailtrap"],
        "env": {
          "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
          "DEFAULT_FROM_EMAIL": "your_sender@example.com",
          "MAILTRAP_ACCOUNT_ID": "your_account_id",
          "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
        }
      }
    }
  }
}

[!TIP] No olvides reiniciar tu servidor MCP después de cambiar la sección "env".

Paquete MCP (MCPB)

Para una instalación sencilla en hosts que admiten MCP Bundles, puedes distribuir un archivo de paquete .mcpb.

# Build TypeScript and pack the MCPB bundle
npm run mcpb:pack

# Inspect bundle metadata
npm run mcpb:info

# Sign the bundle for distribution (optional)
npm run mcpb:sign

Esto crea mailtrap-mcp.mcpb usando el repositorio manifest.json y los artefactos compilados en dist/.

Uso

Una vez configurado, puedes pedirle al agente que envíe correos electrónicos y administre plantillas, por ejemplo:

Operaciones de envío de correos:

• "Envía un correo a john.doe@example.com con el asunto 'Reunión mañana' y un recordatorio amable sobre nuestra próxima reunión."
• "Envía un correo a sarah@example.com sobre la actualización del proyecto, y pon en copia al equipo en team@example.com"
• "Envía la plantilla de bienvenida (uuid b81aabcd-1a1e-41cf-91b6-eca0254b3d96) a new@example.com con las variables { name: 'Alex' }"
• "Envía un correo sandbox a test@example.com con el asunto 'Plantilla de prueba' para previsualizar cómo se ve nuestro correo de bienvenida"

Registros de correo (depuración de entrega):

• "Enumera mis registros de correos enviados recientes"
• "Muestra los registros de correo de los correos enviados a user@example.com"
• "Obtén el mensaje del registro de correo con ID abc-123-uuid para verificar el estado de entrega"

Estadísticas de envío:

• "Obtén estadísticas de envío para enero de 2025"
• "Muestra las tasas de entrega desglosadas por dominio del mes pasado"
• "¿Cuáles son mis estadísticas de correo por categoría del 2025-01-01 al 2025-01-31?"

Operaciones de sandbox:

• "Obtén todos los mensajes de mi bandeja de entrada de sandbox"
• "Muéstrame la primera página de mensajes de sandbox"
• "Busca mensajes que contengan 'test' en mi bandeja de entrada de sandbox"
• "Muéstrame los detalles del mensaje de sandbox con ID 5159037506"

Operaciones de plantillas:

• "Enumera todas las plantillas de correo en mi cuenta de Mailtrap"
• "Crea una nueva plantilla de correo llamada 'Correo de bienvenida' con el asunto '¡Bienvenido a nuestra plataforma!'"
• "Actualiza la plantilla con ID 12345 para cambiar el asunto a 'Mensaje de bienvenida actualizado'"
• "Elimina la plantilla con ID 67890"

Dominios de envío:

• "Enumera mis dominios de envío"
• "Obtén el dominio de envío con ID 3938"
• "Crea un dominio de envío para example.com"
• "Elimina el dominio de envío 3938"
• "Obtén el dominio de envío 3938 con instrucciones de configuración de DNS"

Herramientas disponibles

send-email

Envía un correo electrónico transaccional a través de Mailtrap. Admite dos modos mutuamente excluyentes: contenido en línea (subject + text/html) o basado en plantilla (template_uuid).

Parámetros:

• from (opcional): Remitente como { email, name? } (también se acepta una cadena de correo simple en tiempo de ejecución). Si no se proporciona, se usa DEFAULT_FROM_EMAIL.
• to (opcional): Matriz de destinatarios como objetos { email, name? } (también se aceptan cadenas de correo simples, o una única dirección no matricial, en tiempo de ejecución). Opcional si se proporciona cc o bcc; al menos uno de to / cc / bcc debe contener un destinatario.
• cc (opcional): Matriz de destinatarios en copia (CC) como objetos { email, name? } (también se aceptan cadenas de correo simples en tiempo de ejecución).
• bcc (opcional): Matriz de destinatarios en copia oculta (BCC) como objetos { email, name? } (también se aceptan cadenas de correo simples en tiempo de ejecución).
• subject (condicional): Línea de asunto del correo. Requerido para envíos en línea; debe omitirse cuando template_uuid está establecido.
• text (condicional): Texto del cuerpo del correo. Requerido (junto con html o en su lugar) para envíos en línea; debe omitirse cuando template_uuid está establecido.
• html (condicional): Versión HTML del cuerpo del correo. Requerido (junto con text o en su lugar) para envíos en línea; debe omitirse cuando template_uuid está establecido.
• category (opcional): Categoría del correo para seguimiento y análisis. Debe omitirse cuando template_uuid está establecido.
• template_uuid (opcional): Usa una plantilla de correo de Mailtrap en lugar de contenido en línea. Cuando se establece, subject / text / html / category deben omitirse (según la API de Mailtrap).
• template_variables (opcional): Objeto de variables sustituidas en la plantilla referenciada por template_uuid. Solo se permite junto con template_uuid.

batch-send-transactional-email

Envía un lote de correos electrónicos transaccionales en una sola llamada a la API de Mailtrap (flujo de envío predeterminado). Los campos compartidos van en base; las anulaciones por destinatario van en requests[]. Cada solicitud debe incluir al menos un destinatario mediante to, cc o bcc. La misma exclusión mutua entre en línea y plantilla que send-email — verificada después de combinar la base con cada solicitud.

Parámetros:

• base (opcional): Objeto con campos compartidos en todo el lote.
  • from (opcional): Remitente como { email, name? } (también se acepta una cadena de correo simple en tiempo de ejecución). Recurre a DEFAULT_FROM_EMAIL.
  • reply_to (opcional): Dirección de respuesta (reply-to).
  • subject / text / html / category (opcional, modo en línea): Contenido predeterminado para cada solicitud.
  • template_uuid / template_variables (opcional, modo plantilla): Plantilla + variables predeterminadas. Mutuamente excluyentes con los campos en línea.
  • custom_variables (opcional): Variables personalizadas predeterminadas (con valores de cadena).
  • headers (opcional): Encabezados personalizados predeterminados.
• requests (requerido): Matriz no vacía de mensajes por destinatario. Cada entrada tiene:
  • to (opcional): Matriz de destinatarios como objetos { email, name? } (también se aceptan cadenas de correo simples, o una única dirección no matricial, en tiempo de ejecución). Opcional si se proporciona cc o bcc; al menos uno de to / cc / bcc debe contener un destinatario.
  • cc, bcc, reply_to (opcional).
  • Anulaciones en línea (subject/text/html/category) o de plantilla (template_uuid/template_variables); cualquier campo omitido recurre al valor de base correspondiente.
  • custom_variables, headers (opcional).

batch-send-bulk-email

Envía un lote de correos masivos a través de la API de flujo masivo (bulk-stream) de Mailtrap. La misma forma de base + requests[], validación y reglas de en línea vs. plantilla que batch-send-transactional-email — la única diferencia es que esta herramienta enruta la llamada a través del endpoint masivo en lugar del transaccional. Consulta los parámetros anteriores.

list-email-logs

Enumera los registros de correos enviados (historial de entrega) con paginación y filtros opcionales. Úsalo para depurar problemas de entrega desde el IDE.

Parámetros:

• search_after (opcional): Cursor de paginación del next_page_cursor de la respuesta anterior
• sent_after (opcional): Fecha/hora ISO 8601; solo registros enviados después de este momento
• sent_before (opcional): Fecha/hora ISO 8601; solo registros enviados antes de este momento
• from_email (opcional): Filtro por correo del remitente; usa con from_operator (predeterminado: ci_equal)
• to_email (opcional): Filtro por correo del destinatario; usa con to_operator (predeterminado: ci_equal)
• status (opcional): Filtro por estado de entrega: delivered, not_delivered, enqueued, opted_out; usa con status_operator (predeterminado: equal)
• subject (opcional): Filtro por asunto del correo; usa con subject_operator (predeterminado: ci_contain). Usa subject_operator: empty/not_empty para filtrar por presencia de asunto.
• sending_domain_id (opcional): Filtro por ID de dominio de envío (número); usa con sending_domain_id_operator (predeterminado: equal)
• sending_stream (opcional): Filtro por flujo: transactional o bulk; usa con sending_stream_operator (predeterminado: equal)
• events (opcional): Filtro por tipo(s) de evento: delivery, open, click, bounce, spam, unsubscribe, soft_bounce, reject, suspension; usa con events_operator (include_event / not_include_event)
• clicks_count / opens_count (opcional): Filtro por recuento de clics/aperturas; usa con *_operator: equal, greater_than, less_than
• client_ip / sending_ip (opcional): Filtro por IP; usa con *_operator: equal, not_equal, contain, not_contain
• email_service_provider_response (opcional): Filtro por texto de respuesta del proveedor; usa con *_operator (ci_contain, etc.)
• email_service_provider (opcional): Filtro por proveedor (exacto); usa con *_operator: equal, not_equal
• recipient_mx (opcional): Filtro por MX del destinatario; usa con recipient_mx_operator (ci_contain, etc.)
• category (opcional): Filtro por categoría del correo; usa con category_operator: equal, not_equal

Todos los parámetros son opcionales.

get-email-log-message

Obtiene un único mensaje de registro de correo por ID (UUID): un resumen legible (de, para, asunto, hora de envío, estado, categoría, flujo, interacción, contexto de entrega) y luego el historial detallado de eventos. Opcionalmente, con include_content: true, también puedes cargar y mostrar el cuerpo del mensaje (HTML y texto plano) cuando Mailtrap expone una URL de mensaje sin procesar.

Parámetros:

• message_id (obligatorio): UUID del mensaje de registro de correo (de la respuesta de envío o de list-email-logs). Usa list-email-logs para encontrar los IDs de mensaje.
• include_content (opcional): Cuando true, obtiene el EML sin procesar (si raw_message_url está disponible) y añade las secciones del cuerpo HTML analizado y de texto plano, similar a show-sandbox-email-message.

get-sending-stats

Obtén estadísticas de envío de correo (tasas de entrega, rebote, apertura, clic y spam) para un rango de fechas. Opcionalmente, desglosa por dominio, categoría, proveedor de servicios de correo o fecha. Consulta las tasas de entrega sin salir del editor.

Parámetros:

• start_date (obligatorio): Fecha de inicio para el rango de estadísticas (YYYY-MM-DD)
• end_date (obligatorio): Fecha de fin para el rango de estadísticas (YYYY-MM-DD)
• breakdown (opcional): Cómo desglosar las estadísticas: aggregated (predeterminado), by_domain, by_category, by_email_service_provider o by_date
• sending_domain_ids (opcional): Limita los resultados a estos IDs de dominio de envío (array de enteros)
• sending_streams (opcional): Limita a transactional y/o bulk (array de cadenas)
• categories (opcional): Limita a estas categorías de correo (array de cadenas)
• email_service_providers (opcional): Limita a estos proveedores, p. ej., Google, Yahoo, Outlook (array de cadenas)

create-template

Crea una nueva plantilla de correo en tu cuenta de Mailtrap.

Parámetros:

• name (obligatorio): Nombre de la plantilla
• subject (obligatorio): Línea de asunto del correo
• html (o text es obligatorio): Contenido HTML de la plantilla
• text (o html es obligatorio): Versión en texto plano de la plantilla
• category (opcional): Categoría de la plantilla (el valor predeterminado es "General")

list-templates

Lista todas las plantillas de correo en tu cuenta de Mailtrap.

Parámetros:

• No se requieren parámetros

get-template

Obtén una plantilla de correo individual por ID, incluidos el asunto, la categoría y el cuerpo HTML/texto.

Parámetros:

• template_id (obligatorio): ID de la plantilla a obtener

update-template

Actualiza una plantilla de correo existente.

Parámetros:

• template_id (obligatorio): ID de la plantilla a actualizar
• name (opcional): Nuevo nombre para la plantilla
• subject (opcional): Nueva línea de asunto del correo
• html (opcional): Nuevo contenido HTML de la plantilla
• text (opcional): Nueva versión en texto plano de la plantilla
• category (opcional): Nueva categoría para la plantilla

[!NOTE] Al menos un campo actualizable (name, subject, html, text o category) debe proporcionarse al llamar a update-template para realizar una actualización.

delete-template

Elimina una plantilla de correo existente.

Parámetros:

• template_id (obligatorio): ID de la plantilla a eliminar

send-sandbox-email

Envía un correo a tu bandeja de entrada de prueba de Mailtrap con fines de desarrollo y pruebas. Es perfecto para probar plantillas de correo sin enviar correos a destinatarios reales. Admite los mismos dos modos que send-email — contenido en línea o basado en plantilla (template_uuid).

Parámetros:

• test_inbox_id (opcional): ID de la bandeja de entrada de prueba de Mailtrap. Obligatorio a menos que MAILTRAP_TEST_INBOX_ID esté configurado; pásalo en cada llamada para apuntar a una bandeja de entrada específica.
• from (opcional): Remitente como { email, name? } (también se acepta una cadena de correo simple en tiempo de ejecución). Si no se proporciona, se usa DEFAULT_FROM_EMAIL.
• to (opcional): Array de destinatarios como objetos { email, name? } (también se aceptan cadenas de correo simples en el array, o una cadena separada por comas de correos simples, en tiempo de ejecución). Opcional si se proporciona cc o bcc; al menos uno de to / cc / bcc debe contener un destinatario.
• cc (opcional): Array de destinatarios en CC como objetos { email, name? } (también se aceptan cadenas de correo simples en tiempo de ejecución).
• bcc (opcional): Array de destinatarios en CCO como objetos { email, name? } (también se aceptan cadenas de correo simples en tiempo de ejecución).
• subject (condicional): Línea de asunto del correo. Obligatoria para envíos en línea; debe omitirse cuando template_uuid esté configurado.
• text (condicional): Texto del cuerpo del correo. Obligatorio (junto con o en lugar de html) para envíos en línea; debe omitirse cuando template_uuid esté configurado.
• html (condicional): Versión HTML del cuerpo del correo. Obligatoria (junto con o en lugar de text) para envíos en línea; debe omitirse cuando template_uuid esté configurado.
• category (opcional): Categoría de correo para seguimiento. Debe omitirse cuando template_uuid esté configurado.
• template_uuid (opcional): Usa una plantilla de correo de Mailtrap en lugar de contenido en línea. Cuando esté configurado, subject / text / html / category deben omitirse.
• template_variables (opcional): Objeto de variables sustituidas en la plantilla referenciada por template_uuid. Solo se permite junto con template_uuid.

batch-send-sandbox-email

Envía un lote de correos a tu bandeja de entrada de prueba de Mailtrap en una sola llamada a la API, sin entregarlos a destinatarios reales. Misma forma base + requests[], validación y reglas de en línea vs. plantilla que batch-send-transactional-email — la diferencia es que esta herramienta enruta la llamada a través del endpoint de sandbox para una única bandeja de entrada de prueba.

Parámetros:

• sandbox_id (opcional): ID del sandbox de Mailtrap (bandeja de entrada de prueba). Obligatorio a menos que MAILTRAP_SANDBOX_ID esté configurado; pásalo en cada llamada para apuntar a un sandbox específico.
• base (opcional), requests (obligatorio): Consulta batch-send-transactional-email arriba.

[!NOTE] Para las herramientas de sandbox, proporciona test_inbox_id en la llamada a la herramienta o configura la variable de entorno MAILTRAP_TEST_INBOX_ID. Puedes cambiar entre bandejas de entrada en cada llamada pasando test_inbox_id. Las herramientas que aceptan sandbox_id usan MAILTRAP_SANDBOX_ID primero.

get-sandbox-messages

Recupera una lista de mensajes de tu bandeja de entrada de prueba de Mailtrap. Útil para comprobar qué correos se han recibido en tu sandbox durante las pruebas.

Parámetros:

• page (opcional): Número de página para la paginación (mínimo: 1)
• last_id (opcional): Paginación usando el ID del último mensaje. Devuelve los mensajes posteriores al ID de mensaje especificado (mínimo: 1)
• search (opcional): Consulta de búsqueda para filtrar mensajes

[!NOTE] Todos los parámetros son opcionales. Si no se proporciona ninguno, se devolverá la primera página de mensajes de la bandeja de entrada. Usa page para paginación tradicional, last_id para paginación basada en cursor, o search para filtrar mensajes por contenido.

show-sandbox-email-message

Muestra información detallada y el contenido de un mensaje de correo específico de tu bandeja de entrada de prueba de Mailtrap, incluido el contenido del cuerpo HTML y de texto.

Parámetros:

• message_id (obligatorio): ID del mensaje de correo del sandbox a recuperar

[!NOTE] Usa get-sandbox-messages primero para obtener la lista de mensajes y sus IDs, y luego usa esta herramienta para ver el contenido completo de un mensaje específico.

get-sandbox-project

Obtén un proyecto de sandbox por ID, incluidas sus bandejas de entrada y recuentos de correos.

Parámetros:

• project_id (obligatorio): ID del proyecto a obtener

update-sandbox-project

Cambia el nombre de un proyecto de sandbox existente.

Parámetros:

• project_id (obligatorio): ID del proyecto a actualizar
• name (obligatorio): Nuevo nombre para el proyecto (2–100 caracteres)

list-sandboxes

Lista todos los sandboxes accesibles para el token de API en todos los proyectos.

Parámetros:

• No se requieren parámetros

mark-sandbox-as-read

Marca todos los mensajes de un sandbox como leídos.

Parámetros:

• sandbox_id (obligatorio): ID del sandbox sobre el que actuar

reset-sandbox-credentials

Restablece las credenciales SMTP de un sandbox. Devuelve el nuevo nombre de usuario/contraseña.

Parámetros:

• sandbox_id (obligatorio): ID del sandbox sobre el que actuar

enable-sandbox-email-address

Habilita la dirección de recepción por correo para un sandbox (activa la dirección de Mailtrap que entrega mensajes al sandbox mediante SMTP).

Parámetros:

• sandbox_id (obligatorio): ID del sandbox sobre el que actuar

reset-sandbox-email-address

Genera una nueva dirección de recepción por correo para un sandbox.

Parámetros:

• sandbox_id (obligatorio): ID del sandbox sobre el que actuar

forward-sandbox-message

Reenvía un mensaje del sandbox a una dirección de correo externa. Cuenta contra tu cuota mensual de reenvío.

Parámetros:

• sandbox_id (opcional): ID del sandbox. Recurre a MAILTRAP_SANDBOX_ID.
• message_id (obligatorio): ID del mensaje del sandbox a reenviar
• email (obligatorio): Dirección de correo a la que reenviar el mensaje

update-sandbox-message

Marca un mensaje del sandbox como leído o no leído.

Parámetros:

• sandbox_id (opcional): ID del sandbox. Recurre a MAILTRAP_SANDBOX_ID.
• message_id (obligatorio): ID del mensaje del sandbox a actualizar
• is_read (obligatorio): true marca como leído, false marca como no leído

delete-sandbox-message

Elimina un único mensaje del sandbox.

Parámetros:

• sandbox_id (opcional): ID del sandbox. Recurre a MAILTRAP_SANDBOX_ID.
• message_id (obligatorio): ID del mensaje del sandbox a eliminar

get-sandbox-message-spam-score

Obtén el informe de spam de SpamAssassin para un mensaje del sandbox (puntuación, reglas, informe completo). Alternativa independiente a include_spam_report: true en show-sandbox-email-message.

Parámetros:

• sandbox_id (opcional): ID del sandbox. Recurre a MAILTRAP_SANDBOX_ID.
• message_id (obligatorio): ID del mensaje del sandbox

get-sandbox-message-html-analysis

Obtén el informe de análisis HTML para un mensaje del sandbox (puntuaciones de compatibilidad con clientes, elementos problemáticos). Alternativa independiente a include_html_analysis: true en show-sandbox-email-message.

Parámetros:

• sandbox_id (opcional): ID del sandbox. Recurre a MAILTRAP_SANDBOX_ID.
• message_id (obligatorio): ID del mensaje del sandbox

get-sandbox-message-headers

Obtén las cabeceras de correo analizadas para un mensaje del sandbox.

Parámetros:

• sandbox_id (opcional): ID del sandbox. Recurre a MAILTRAP_SANDBOX_ID.
• message_id (obligatorio): ID del mensaje del sandbox

get-sandbox-message-html

Obtén el cuerpo HTML renderizado de un mensaje del sandbox.

Parámetros:

• sandbox_id (opcional): ID del sandbox. Recurre a MAILTRAP_SANDBOX_ID.
• message_id (obligatorio): ID del mensaje del sandbox

get-sandbox-message-text

Obtén el cuerpo en texto plano de un mensaje del sandbox.

Parámetros:

• sandbox_id (opcional): ID del sandbox. Recurre a MAILTRAP_SANDBOX_ID.
• message_id (obligatorio): ID del mensaje del sandbox

get-sandbox-message-raw

Obtén el mensaje sin procesar, con formato MIME (cabeceras + cuerpo), para un mensaje del sandbox.

Parámetros:

• sandbox_id (opcional): ID del sandbox. Recurre a MAILTRAP_SANDBOX_ID.
• message_id (obligatorio): ID del mensaje del sandbox

get-sandbox-message-eml

Obtén el mensaje renderizado como carga útil de archivo EML (adecuado para adjuntar a un ticket o importar en otro cliente de correo).

Parámetros:

• sandbox_id (opcional): ID del sandbox. Recurre a MAILTRAP_SANDBOX_ID.
• message_id (obligatorio): ID del mensaje del sandbox

get-sandbox-message-html-source

Obtén el código fuente HTML sin renderizar de un mensaje del sandbox (HTML antes de cualquier transformación del lado de Mailtrap, como reescrituras de enlaces CID).

Parámetros:

• sandbox_id (opcional): ID del sandbox. Recurre a MAILTRAP_SANDBOX_ID.
• message_id (obligatorio): ID del mensaje del sandbox

list-sandbox-attachments

Lista todos los adjuntos de un mensaje del sandbox (nombre de archivo, tipo de contenido, tamaño, ruta de descarga).

Parámetros:

• sandbox_id (opcional): ID del sandbox. Recurre a MAILTRAP_SANDBOX_ID.
• message_id (obligatorio): ID del mensaje del sandbox

get-sandbox-attachment

Obtén los metadatos y la URL de descarga de un único adjunto.

Parámetros:

• sandbox_id (opcional): ID de sandbox. Recurre a MAILTRAP_SANDBOX_ID.
• message_id (obligatorio): ID del mensaje de sandbox que contiene el adjunto
• attachment_id (obligatorio): ID del adjunto a recuperar

list-sending-domains

Lista los dominios de envío y su estado de verificación DNS.

Parámetros:

• No se requieren parámetros

get-sending-domain

Obtén un dominio de envío por su ID y su estado de verificación (incluyendo registros DNS). Opcionalmente, incluye instrucciones de configuración DNS estableciendo include_setup_instructions en true.

Parámetros:

• sending_domain_id (obligatorio): ID del dominio de envío
• include_setup_instructions (opcional): Si true, añade instrucciones de configuración DNS a la respuesta. Por defecto: false

create-sending-domain

Crea un nuevo dominio de envío. Después de la creación, añade registros DNS para verificar el dominio (usa get-sending-domain con include_setup_instructions: true para ver los registros).

Parámetros:

• domain_name (obligatorio): Nombre del dominio (p. ej., example.com)

delete-sending-domain

Elimina un dominio de envío.

Parámetros:

• sending_domain_id (obligatorio): ID del dominio de envío a eliminar

send-sending-domain-setup-instructions

Envía por correo electrónico las instrucciones de configuración DNS para un dominio de envío a una dirección dada. Útil para reenviar registros DNS a un compañero de DevOps.

Parámetros:

• sending_domain_id (obligatorio): ID del dominio de envío
• email (obligatorio): Dirección de correo electrónico a la que enviar las instrucciones de configuración DNS

list-suppressions

Lista o busca supresiones (rebotes duros, quejas de spam, cancelaciones de suscripción, importaciones manuales). Devuelve hasta 1000 resultados por llamada.

Parámetros:

• email (opcional): Filtro de correo electrónico. Devuelve solo las supresiones que coincidan con esta dirección.

delete-suppression

Elimina una supresión por su ID. Mailtrap reanudará la entrega a este correo electrónico a menos que se vuelva a suprimir.

Parámetros:

• suppression_id (obligatorio): ID de la supresión a eliminar

list-webhooks

Lista todos los webhooks configurados para la cuenta. Devuelve los registros completos de los webhooks como JSON.

Parámetros:

• No se requieren parámetros

get-webhook

Obtén un solo webhook por su ID. Devuelve el registro completo del webhook como JSON. Nota: signing_secret no se devuelve aquí; solo está disponible en la respuesta de create-webhook.

Parámetros:

• webhook_id (obligatorio): ID del webhook a recuperar

create-webhook

Crea un webhook. La respuesta incluye un signing_secret para verificar las firmas de las cargas útiles del webhook; este secreto se devuelve solo en la creación, así que guárdalo ahora. Si lo pierdes, recrea el webhook.

Parámetros:

• url (obligatorio): URL a la que Mailtrap publicará los eventos del webhook
• webhook_type (obligatorio): "email_sending", "audit_log" o "inbound_receiving"
• active (opcional, booleano): el valor predeterminado es true
• payload_format (opcional): "json" o "jsonlines". El valor predeterminado es "json"
• sending_stream (opcional, solo email_sending): "transactional" o "bulk"
• event_types (opcional, solo email_sending): matriz de delivery, soft_bounce, bounce, suspension, unsubscribe, open, spam_complaint, click, reject
• domain_id (opcional, solo email_sending): ID del dominio de envío para delimitar este webhook
• inbound_inbox_id (opcional, solo inbound_receiving): ID de la bandeja de entrada entrante a la que está vinculado el webhook; omítelo para aplicar a todas las bandejas de entrada de la cuenta

update-webhook

Actualiza los campos mutables de un webhook. webhook_type, sending_stream y domain_id no se pueden cambiar después de la creación; recrea el webhook si necesitas cambiarlos.

Parámetros:

• webhook_id (obligatorio): ID del webhook a actualizar
• url (opcional): Nueva URL del webhook
• active (opcional, booleano): Habilita o deshabilita el webhook
• payload_format (opcional): "json" o "jsonlines"
• event_types (opcional, solo email_sending): matriz de delivery, soft_bounce, bounce, suspension, unsubscribe, open, spam_complaint, click, reject
• inbound_inbox_id (opcional, solo inbound_receiving): ID de la bandeja de entrada entrante a la que está vinculado el webhook

delete-webhook

Elimina permanentemente un webhook por su ID. Devuelve el registro del webhook eliminado.

Parámetros:

• webhook_id (obligatorio): ID del webhook a eliminar

get-contact

Obtén un contacto por ID o correo electrónico. Devuelve el registro completo del contacto (membresías de listas, estado, campos personalizados).

Parámetros:

• contact_identifier (obligatorio): ID del contacto o dirección de correo electrónico

create-contact

Crea un nuevo contacto.

Parámetros:

• email (obligatorio): Dirección de correo electrónico
• fields (opcional): Valores de campos personalizados claveados por etiqueta de combinación (p. ej., first_name). Valores de cadena, número o booleano
• list_ids (opcional): IDs de listas de contactos para suscribir a este contacto
• unsubscribed (opcional, booleano): Crear el contacto en estado unsubscribed

update-contact

Actualiza un contacto existente identificado por ID o correo electrónico. list_ids reemplaza el conjunto completo de membresías del contacto; list_ids_included/list_ids_excluded agregan/eliminan sin alterar el resto.

Parámetros:

• contact_identifier (obligatorio): ID del contacto o correo electrónico
• email (opcional): Nueva dirección de correo electrónico
• fields (opcional): Valores de campos personalizados claveados por etiqueta de combinación
• list_ids (opcional): Reemplaza el conjunto de membresías con esta lista exacta
• list_ids_included (opcional): IDs de listas a agregar (aditivo)
• list_ids_excluded (opcional): IDs de listas a eliminar
• unsubscribed (opcional, booleano): Establece en unsubscribed (verdadero) o subscribed (falso)

delete-contact

Elimina permanentemente un contacto por ID o correo electrónico. Devuelve el registro del contacto eliminado cuando la API responde con uno; de lo contrario, devuelve un payload de confirmación.

Parámetros:

• contact_identifier (obligatorio): ID del contacto o correo electrónico

create-contact-event

Registra un evento de contacto contra un contacto (por ID o correo electrónico). Se usa para activar automatizaciones de listas de contactos.

Parámetros:

• contact_identifier (obligatorio): ID del contacto o correo electrónico
• name (obligatorio): Nombre del evento (coincide con los disparadores de automatización)
• params (obligatorio): Objeto de pares clave/valor arbitrarios. Los valores pueden ser cadena, número, booleano o nulo

list-contact-lists

Lista todas las listas de contactos de la cuenta.

Parámetros:

• search (opcional): Filtra las listas de contactos por nombre (coincidencia sin distinguir mayúsculas y minúsculas), p. ej., news

get-contact-list

Obtén una lista de contactos por su ID.

Parámetros:

• list_id (obligatorio): ID de la lista de contactos a recuperar

create-contact-list

Crea una nueva lista de contactos.

Parámetros:

• name (obligatorio): Nombre para la nueva lista

update-contact-list

Renombra una lista de contactos existente.

Parámetros:

• list_id (obligatorio): ID de la lista de contactos
• name (obligatorio): Nuevo nombre para la lista

delete-contact-list

Elimina permanentemente una lista de contactos por su ID.

Parámetros:

• list_id (obligatorio): ID de la lista de contactos a eliminar

list-contact-fields

Lista todas las definiciones de campos de contacto de la cuenta.

Parámetros:

• No se requieren parámetros

get-contact-field

Obtén una definición de campo de contacto por su ID.

Parámetros:

• field_id (obligatorio): ID del campo de contacto

create-contact-field

Crea una nueva definición de campo de contacto. merge_tag debe ser único dentro de la cuenta y se usa como nombre de marcador de posición en las variables de plantilla.

Parámetros:

• name (obligatorio): Nombre para mostrar (p. ej., "Nombre")
• merge_tag (obligatorio): Nombre de marcador de posición único (p. ej., first_name)
• data_type (obligatorio): Uno de text, number, boolean, date

update-contact-field

Actualiza una definición de campo de contacto. Se puede cambiar cualquier combinación de name, merge_tag y data_type.

Parámetros:

• field_id (obligatorio): ID del campo de contacto
• name (opcional): Nuevo nombre para mostrar
• merge_tag (opcional): Nueva etiqueta de combinación (debe permanecer única)
• data_type (opcional): Uno de text, number, boolean, date

delete-contact-field

Elimina permanentemente una definición de campo de contacto por su ID.

Parámetros:

• field_id (obligatorio): ID del campo de contacto a eliminar

create-contact-import

Importa contactos en masa. Devuelve un registro de trabajo de importación; consulta su estado con get-contact-import.

Parámetros:

• contacts (obligatorio): Matriz de entradas de contacto. Cada entrada necesita:
  • email (obligatorio): Dirección de correo electrónico del contacto
  • fields (opcional): Valores de campos personalizados claveados por etiqueta de combinación (valores de cadena o número)
  • list_ids_included (opcional): IDs de listas a los que agregar el contacto
  • list_ids_excluded (opcional): IDs de listas de las que eliminar el contacto

get-contact-import

Obtén el estado de un trabajo de importación de contactos (creado/iniciado/finalizado/fallido) con contadores de creados/actualizados/superados.

Parámetros:

• import_id (obligatorio): ID del trabajo de importación de contactos

create-contact-export

Exporta contactos que coincidan con un conjunto de filtros combinados con AND. Devuelve un registro de trabajo de exportación; consulta el estado con get-contact-export para recuperar la URL de descarga una vez que status sea finished.

Parámetros:

• filters (obligatorio): Matriz de objetos de filtro. Cada uno tiene:
  • name (obligatorio): Campo sobre el que filtrar (list_id, subscription_status, email, etc.)
  • operator (obligatorio): Uno de equal, not_equal, contains, not_contains, is_empty, is_not_empty
  • value (obligatorio): Valor de comparación (cadena, número, booleano o matriz)

get-contact-export

Obtén el estado de un trabajo de exportación de contactos. Una vez que status sea finished, el campo url contiene el enlace de descarga CSV.

Parámetros:

• export_id (obligatorio): ID del trabajo de exportación de contactos

list-accounts

Lista las cuentas de Mailtrap a las que el token de API actual puede acceder, con los niveles de acceso de cada cuenta.

Parámetros:

• No se requieren parámetros

get-billing-usage

Obtén el uso actual del ciclo de facturación de la cuenta: planes de envío y pruebas, límites y recuentos actuales.

Parámetros:

• No se requieren parámetros

list-account-accesses

Lista los accesos a la cuenta (usuarios, invitaciones, tokens de API). Los filtros opcionales limitan el resultado a recursos específicos. Requiere permisos de administrador/propietario de la cuenta.

Parámetros:

• domain_uuids (opcional): Filtra por UUID de dominios de envío (matriz de cadenas)
• inbox_ids (opcional): Filtra por IDs de bandejas de entrada de sandbox (matriz de cadenas)
• project_ids (opcional): Filtra por IDs de proyectos de sandbox (matriz de cadenas)

remove-account-access

Elimina un acceso a la cuenta por su ID. Para especificadores de User, esto revoca sus permisos; para especificadores de Invite o ApiToken, elimina el especificador por completo. Requiere administrador/propietario.

Parámetros:

• account_access_id (obligatorio): ID del registro de acceso a eliminar

get-permission-resources

Obtén todos los recursos (bandejas de entrada, proyectos, dominios, facturación, cuenta) a los que el token de API tiene acceso de administrador, anidados por jerarquía.

Parámetros:

• No se requieren parámetros

bulk-update-permissions

Crea, actualiza o destruye permisos en masa para un único acceso a la cuenta. Los pares (resource_type, resource_id) existentes se actualizan; los nuevos se crean. Establece destroy: true en una entrada para eliminarla.

Parámetros:

• account_access_id (obligatorio): ID de acceso de la cuenta de destino
• permissions (obligatorio): Matriz de entradas de permiso. Cada una tiene:
  • resource_id (obligatorio): ID del recurso (número o cadena)
  • resource_type (obligatorio): Uno de account, project, inbox, domain, billing
  • access_level (opcional): admin/100 o viewer/10
  • destroy (opcional, booleano): Cuando es true, elimina este permiso en lugar de crearlo/actualizarlo

list-api-tokens

Lista todos los tokens de API de la cuenta.

Parámetros:

• No se requieren parámetros

create-api-token

Crea un nuevo token de API. La respuesta incluye el valor secreto token — esta es la única vez que se devuelve el token completo, así que guárdalo inmediatamente. Si lo pierdes, recrea el token.

Parámetros:

• name (obligatorio): Nombre para mostrar del token
• resources (opcional): Matriz de permisos de recursos para delimitar el token. Cada entrada tiene:
  • resource_type (obligatorio): Uno de account, project, inbox, domain, billing
  • resource_id (obligatorio): ID del recurso
  • access_level (obligatorio): 100 (admin) o 10 (viewer)

get-api-token

Obtiene un token de API por ID. Devuelve solo metadatos: el valor secreto del token no se devuelve aquí (solo desde create-api-token / reset-api-token).

Parámetros:

• api_token_id (obligatorio): ID del token de API

reset-api-token

Restablece (rota) un token de API por ID. La respuesta incluye el nuevo valor secreto token — se devuelve solo en esta llamada, así que guárdalo inmediatamente. El token anterior se invalida.

Parámetros:

• api_token_id (obligatorio): ID del token de API a restablecer

delete-api-token

Elimina permanentemente un token de API por ID. El token ya no puede autenticarse después de la eliminación.

Parámetros:

• api_token_id (obligatorio): ID del token de API a eliminar

list-sub-accounts

Lista las subcuentas de la organización. Requiere la variable de entorno MAILTRAP_ORGANIZATION_ID y permisos de gestión de subcuentas.

Parámetros:

• No se requieren parámetros

create-sub-account

Crea una nueva subcuenta dentro de la organización. Requiere la variable de entorno MAILTRAP_ORGANIZATION_ID y permisos de gestión de subcuentas.

Parámetros:

• name (obligatorio): Nombre para mostrar de la nueva subcuenta

list-inbound-folders

Lista todas las carpetas de entrada de la cuenta. Devuelve un resumen formateado.

Parámetros:

• No se requieren parámetros

get-inbound-folder

Obtiene una carpeta de entrada por ID. Devuelve el registro completo de la carpeta como JSON.

Parámetros:

• folder_id (obligatorio): ID de la carpeta de entrada

create-inbound-folder

Crea una nueva carpeta de entrada.

Parámetros:

• name (obligatorio): El nombre de la carpeta

update-inbound-folder

Cambia el nombre de una carpeta de entrada.

Parámetros:

• folder_id (obligatorio): ID de la carpeta de entrada
• name (obligatorio): El nuevo nombre de la carpeta

delete-inbound-folder

Elimina permanentemente una carpeta de entrada junto con todas sus bandejas de entrada.

Parámetros:

• folder_id (obligatorio): ID de la carpeta de entrada

list-inbound-inboxes

Lista todas las bandejas de entrada de una carpeta de entrada. Devuelve un resumen formateado.

Parámetros:

• folder_id (obligatorio): ID de la carpeta de entrada

get-inbound-inbox

Obtiene una bandeja de entrada por ID. Devuelve el registro completo de la bandeja de entrada como JSON.

Parámetros:

• folder_id (obligatorio): ID de la carpeta de entrada
• inbox_id (obligatorio): ID de la bandeja de entrada

create-inbound-inbox

Crea una nueva bandeja de entrada en una carpeta.

Parámetros:

• folder_id (obligatorio): ID de la carpeta de entrada
• name (obligatorio): El nombre de la bandeja de entrada
• domain_id (opcional): Adjuntar a un dominio de envío personalizado (bandeja de entrada catch-all). Omitir para una bandeja de entrada alojada en Mailtrap

update-inbound-inbox

Cambia el nombre de una bandeja de entrada.

Parámetros:

• folder_id (obligatorio): ID de la carpeta de entrada
• inbox_id (obligatorio): ID de la bandeja de entrada
• name (obligatorio): El nuevo nombre de la bandeja de entrada

delete-inbound-inbox

Elimina permanentemente una bandeja de entrada.

Parámetros:

• folder_id (obligatorio): ID de la carpeta de entrada
• inbox_id (obligatorio): ID de la bandeja de entrada

list-inbound-messages

Lista los mensajes recibidos en una bandeja de entrada (paginados por cursor). Devuelve un resumen formateado con una pista de página siguiente cuando existen más resultados.

Parámetros:

• inbox_id (obligatorio): ID de la bandeja de entrada
• last_id (opcional): Cursor de paginación del last_id de una respuesta anterior

get-inbound-message

Obtiene un mensaje de entrada con su cuerpo completo y las URL de descarga de adjuntos. Devuelve el registro completo del mensaje como JSON.

Parámetros:

• inbox_id (obligatorio): ID de la bandeja de entrada
• message_id (obligatorio): ID del mensaje

delete-inbound-message

Elimina permanentemente un mensaje de entrada.

Parámetros:

• inbox_id (obligatorio): ID de la bandeja de entrada
• message_id (obligatorio): ID del mensaje

reply-to-inbound-message

Responde a un mensaje de entrada (envía al remitente original). Envía un correo electrónico real. Las direcciones aceptan una cadena de correo simple o { email, name? }.

Parámetros:

• inbox_id (obligatorio): ID de la bandeja de entrada
• message_id (obligatorio): ID del mensaje al que responder
• text / html (al menos uno recomendado): Cuerpo de la respuesta
• from (opcional): Remitente. Rechazado para bandejas de entrada alojadas en Mailtrap; requerido para bandejas de entrada con dominio personalizado
• cc / bcc / reply_to (opcional): Direcciones adicionales
• category (opcional): Categoría del mensaje
• attachments (opcional): Matriz de { content (base64), filename, type?, disposition?, content_id? }
• headers / custom_variables (opcional): Objetos de valores de cadena

reply-all-to-inbound-message

Responde a un mensaje de entrada y copia a los demás destinatarios del original. Envía un correo electrónico real. Mismos parámetros que reply-to-inbound-message.

Parámetros:

• inbox_id (obligatorio): ID de la bandeja de entrada
• message_id (obligatorio): ID del mensaje al que responder
• Más los mismos campos de envío opcionales que reply-to-inbound-message

forward-inbound-message

Reenvía un mensaje de entrada a nuevos destinatarios. Envía un correo electrónico real.

Parámetros:

• inbox_id (obligatorio): ID de la bandeja de entrada
• message_id (obligatorio): ID del mensaje a reenviar
• to (obligatorio): Al menos un destinatario (cadena de correo simple o { email, name? }, o una matriz)
• Más los mismos campos de envío opcionales que reply-to-inbound-message

list-inbound-threads

Lista los hilos de conversación en una bandeja de entrada (paginados por cursor). Devuelve un resumen formateado con una pista de página siguiente cuando existen más resultados.

Parámetros:

• inbox_id (obligatorio): ID de la bandeja de entrada
• last_id (opcional): Cursor de paginación del last_id de una respuesta anterior

get-inbound-thread

Obtiene un hilo de entrada con sus mensajes incrustados (del más antiguo al más reciente). Devuelve el registro completo del hilo como JSON.

Parámetros:

• inbox_id (obligatorio): ID de la bandeja de entrada
• thread_id (obligatorio): ID del hilo

delete-inbound-thread

Elimina permanentemente un hilo de entrada.

Parámetros:

• inbox_id (obligatorio): ID de la bandeja de entrada
• thread_id (obligatorio): ID del hilo

Desarrollo

1. Clona el repositorio:

git clone https://github.com/mailtrap/mailtrap-mcp.git
cd mailtrap-mcp

2. Instala las dependencias:

npm install

Configuración con Claude Desktop o Cursor

[!TIP] Consulta la ubicación del archivo de configuración en la sección Setup.

Añade la siguiente configuración:

{
  "mcpServers": {
    "mailtrap": {
      "command": "node",
      "args": ["/path/to/mailtrap-mcp/dist/index.js"],
      "env": {
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "your_sender@example.com",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

Si usas asdf para gestionar Node.js, debes usar la ruta absoluta al ejecutable:

(ejemplo para Mac)

{
  "mcpServers": {
    "mailtrap": {
      "command": "/Users/<username>/.asdf/shims/node",
      "args": ["/path/to/mailtrap-mcp/dist/index.js"],
      "env": {
        "PATH": "/Users/<username>/.asdf/shims:/usr/bin:/bin",
        "ASDF_DIR": "/opt/homebrew/opt/asdf/libexec",
        "ASDF_DATA_DIR": "/Users/<username>/.asdf",
        "ASDF_NODEJS_VERSION": "20.6.1",
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "your_sender@example.com",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

VS Code

[!TIP] Consulta la ubicación del archivo de configuración en la sección Setup.

{
  "mcp": {
    "servers": {
      "mailtrap": {
        "command": "node",
        "args": ["/path/to/mailtrap-mcp/dist/index.js"],
        "env": {
          "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
          "DEFAULT_FROM_EMAIL": "your_sender@example.com",
          "MAILTRAP_ACCOUNT_ID": "your_account_id",
          "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
        }
      }
    }
  }
}

Pruebas

Ejecutar herramientas contra Mailtrap real

Hay dos formas de probar una herramienta de extremo a extremo contra una cuenta real de Mailtrap: la interfaz de navegador del MCP Inspector para exploración interactiva, o su modo CLI para llamadas puntuales desde la shell.

Ambas requieren que el bundle se compile primero:

npm run build

y MAILTRAP_API_TOKEN + MAILTRAP_ACCOUNT_ID exportados en tu shell (el script mcp:cli reenvía ambos al servidor generado).

Interfaz de navegador

npm run dev

El Inspector imprime una URL como http://localhost:6274. Ábrela, cambia a la pestaña Tools, elige una herramienta (p. ej. get-template), rellena los parámetros como JSON y pulsa Run. La respuesta de Mailtrap aparece en el panel inferior.

CLI

Para llamadas puntuales sin la interfaz, usa npm run mcp:cli. Pasa las banderas CLI del Inspector después de -- para que npm las reenvíe tal cual:

# List all tools
npm run mcp:cli -- --method tools/list

# Call a tool — flags after the `--`
npm run mcp:cli -- \
  --method tools/call \
  --tool-name get-template \
  --tool-arg template_id=12345

# Multiple --tool-arg flags for tools with several params
npm run mcp:cli -- \
  --method tools/call \
  --tool-name send-sending-domain-setup-instructions \
  --tool-arg sending_domain_id=3938 \
  --tool-arg email=devops@example.com

Ejecutar el servidor MCPB

# Run the MCPB server directly
node dist/mcpb-server.js

# Or use the provided binary
mailtrap-mcpb-server

[!TIP] Para desarrollo con el MCP Inspector:

npm run dev:mcpb

Manejo de errores

Este servidor utiliza un manejo de errores estructurado alineado con las convenciones de MCP:

• VALIDATION_ERROR: Fallos de validación de entrada
• CONFIGURATION_ERROR: Configuración faltante o no válida
• EXECUTION_ERROR: Errores de ejecución en tiempo de ejecución
• TIMEOUT: Tiempo de espera de operación (30 segundos por defecto)

Los errores incluyen mensajes accionables y se registran de forma estructurada.

Seguridad

• Entrada validada mediante esquemas Zod
• Variables de entorno gestionadas de forma segura
• Protección de tiempo de espera en operaciones (30 segundos)
• Detalles sensibles saneados en la salida de errores

Registro

Registros JSON estructurados con niveles: INFO, WARN, ERROR, DEBUG.

Habilita el registro de depuración configurando DEBUG=true.

# Example: enable debug logging
DEBUG=true node dist/mcpb-server.js

Importante: el servidor escribe los registros en stderr para que stdout permanezca reservado para las tramas JSON-RPC. Esto evita que los hosts encuentren errores de análisis JSON debido a registros intercalados.

Ejemplo de análisis de registros usando jq:

# Filter error logs
node dist/mcpb-server.js 2>&1 | jq 'select(.level == "error")'

# Filter debug logs
node dist/mcpb-server.js 2>&1 | jq 'select(.level == "debug")'

Solución de problemas

Problemas comunes:

1. Token de API faltante: asegúrate de que MAILTRAP_API_TOKEN esté configurado
2. Sandbox que no funciona: proporciona test_inbox_id en la llamada a la herramienta o configura la variable de entorno MAILTRAP_TEST_INBOX_ID
3. Errores de tiempo de espera: comprueba la conectividad de red y el estado de la API de Mailtrap
4. Errores de validación: asegúrate de que todos los campos obligatorios estén presentes

Contribuciones

Los informes de errores y las solicitudes de extracción son bienvenidos en GitHub. Este proyecto pretende ser un espacio seguro y acogedor para la colaboración, y se espera que los contribuyentes cumplan el código de conducta.

Licencia

El paquete está disponible como código abierto bajo los términos de la Licencia MIT.

Código de conducta

Se espera que todas las personas que interactúan en los repositorios de código, rastreadores de problemas, salas de chat y listas de correo del proyecto Mailtrap sigan el código de conducta.