Cakemail MCP Server

Gestiona campañas de marketing por correo electrónico, contactos y correos transaccionales con la API de Cakemail.

Documentación

Servidor MCP de Cakemail

Un servidor de Protocolo de Contexto de Modelo (MCP) empresarial para integrarse con la API de Cakemail. Este servidor proporciona herramientas integrales para campañas de marketing por correo electrónico, correos transaccionales, informes detallados, diseño visual avanzado de correos con BEEeditor, gestión de plantillas y gestión completa de listas a través de la plataforma Cakemail.

🎯 Versión 1.10.0 - Gestión Completa de Plantillas

Esta versión introduce funcionalidad integral de gestión de plantillas, proporcionando gestión completa del ciclo de vida de plantillas de correo electrónico, incluyendo creación, actualización, duplicación y capacidades avanzadas de filtrado con soporte para estructuras modernas de contenido OpenAPI.

✨ Funcionalidades Actualmente Implementadas

🎨 Gestión de Plantillas (7 herramientas)

✅ Crear, actualizar y eliminar plantillas de correo con estructura de contenido moderna
✅ Listar plantillas con filtrado avanzado, ordenación y paginación
✅ Obtener detalles individuales de plantillas y metadatos
✅ Duplicar plantillas con nombres inteligentes y preservación de etiquetas
✅ Renderizar plantillas para vista previa HTML y pruebas
✅ Estructura de contenido compatible con OpenAPI (html, text, bee, custom)
✅ Compatibilidad hacia atrás con formatos de plantilla heredados
✅ Soporte multi-cuenta para entornos empresariales
✅ Filtrado avanzado por etiquetas, nombre, estado de propiedad
✅ Búsqueda de plantillas por nombre, etiquetas o propiedad

👥 Gestión de Contactos

✅ Crear, actualizar y eliminar contactos con campos personalizados
✅ Listar contactos con filtrado por ID de lista
✅ Soporte avanzado de segmentación de contactos
✅ Métricas de participación de contactos

📧 Gestión de Campañas (21 herramientas)

✅ Crear, actualizar y eliminar campañas de correo electrónico
✅ Listar campañas con filtrado avanzado y paginación
✅ Enviar campañas a listas de contactos
✅ Métricas de rendimiento de campañas (a través de la API de Informes)
✅ Obtener la última campaña con un solo comando
✅ Integración con BEEeditor para diseño visual de correos
✅ Plantillas de correo basadas en JSON con estructura de arrastrar y soltar
✅ Generación de plantillas de boletines con diseño automatizado
✅ Programación de campañas, suspensión y gestión del ciclo de vida
✅ Pruebas de campañas, vista previa e historial de revisiones
✅ Archivado de campañas y seguimiento de enlaces

📋 Gestión de Listas (7 herramientas)

✅ Crear, actualizar y eliminar listas de contactos
✅ Listar todas las listas con filtrado avanzado y paginación
✅ Obtener información detallada de listas y estadísticas
✅ Archivar listas preservando datos
✅ Análisis integral de rendimiento de listas
✅ Soporte multi-idioma y configuración de remitentes
✅ Integración de webhooks para eventos de listas en tiempo real
✅ Alcance de cuentas para entornos empresariales

📨 Correo Transaccional (10 herramientas)

✅ Enviar correos transaccionales y de marketing individuales
✅ Seguimiento de estado de correos y monitoreo de entrega
✅ Soporte de contenido HTML y texto plano
✅ Capacidades de renderizado y vista previa de correos
✅ Registros integrales de actividad de correos con filtrado
✅ Estadísticas de correos con análisis basado en tiempo
✅ Registros avanzados de correos con análisis de rendimiento
✅ Herramientas de depuración para pruebas de API de correos

🏢 Gestión Empresarial de Sub-Cuentas (14 herramientas)

✅ Crear, actualizar y eliminar sub-cuentas
✅ Soporte multi-tenant para agencias
✅ Suspensión/activación de cuentas
✅ Conversión de organizaciones
✅ Flujos de trabajo de verificación de correos
✅ Capacidades avanzadas de filtrado y búsqueda
✅ Utilidades de depuración y resolución de problemas

📊 Informes y Análisis Mejorados (12 herramientas)

✅ Arquitectura Modular de Informes con módulos enfocados y mantenibles
✅ Análisis de Campañas con información detallada de rendimiento y análisis de enlaces
✅ Estadísticas de API de Correos para rendimiento de correos transaccionales
✅ Análisis de Listas y Cuentas con métricas de crecimiento y salud de entregabilidad
✅ Evaluación Comparativa Inteligente de Rendimiento con comparaciones estándar de la industria
✅ Análisis Inteligente de Enlaces con categorización automática y optimización
✅ Indicadores Visuales de Rendimiento (🚀👍 ⚠️ 🛑) para evaluación rápida
✅ Recomendaciones Accionables basadas en patrones de rendimiento
✅ Gestión de Exportaciones con seguimiento de progreso y gestión del ciclo de vida
✅ Exportación de Informes de Campañas (CSV/XLSX) con datos integrales
✅ Exportación de Correos Suprimidos para cumplimiento y entregabilidad
✅ Herramientas de Depuración para pruebas de conectividad de API

📋 Registros y Seguimiento de Eventos (6 herramientas)

✅ Registros de actividad de campañas con análisis avanzado de secuencias
✅ Registros de automatización de flujos de trabajo
✅ Registros de entrega de correos transaccionales
✅ Registros de actividad de listas de contactos
✅ Filtrado inteligente y categorización de eventos
✅ Herramientas de depuración para pruebas de API de registros

👤 Gestión de Remitentes (5 herramientas)

✅ Crear, actualizar y eliminar remitentes verificados
✅ Listar todos los remitentes con estado de verificación
✅ Soporte completo de autenticación de remitentes

🎨 Diseño Visual con BEEeditor (3 herramientas)

✅ Crear estructuras básicas de plantillas BEEeditor
✅ Generar plantillas completas de boletines con secciones
✅ Validar plantillas JSON de BEE contra el esquema
✅ Capacidades de diseño de correos con arrastrar y soltar

🏢 Gestión de Cuentas (2 herramientas)

✅ Obtener detalles e información actuales de la cuenta
✅ Ver configuración de reintentos y ajustes de API
✅ Monitoreo de salud de cuentas y diagnósticos

🏥 Infraestructura de Producción

✅ Monitoreo de salud y validación de conexión de API
✅ Autenticación OAuth 2.0 con renovación automática de tokens
✅ Lógica de reintentos con retroceso exponencial
✅ Limitación de velocidad y protección de interruptor de circuito
✅ Cola de solicitudes y control de concurrencia
✅ Manejo integral de errores

Total Implementado: 87+ herramientas en 11 categorías de funcionalidades

🚀 Inicio Rápido

Requisitos Previos

Node.js 18 o superior
Cuenta de Cakemail con acceso a API
Claude Desktop u otro cliente compatible con MCP

Instalación

Clonar el repositorio:

git clone https://github.com/cakemail/cakemail-mcp-server.git
cd cakemail-mcp-server

Instalar dependencias:

npm install

Compilar el proyecto:

npm run build

Configuración

Variables de Entorno

Cree un archivo .env en la raíz del proyecto:

CAKEMAIL_USERNAME=your-email@example.com
CAKEMAIL_PASSWORD=your-password
CAKEMAIL_BASE_URL=https://api.cakemail.dev

Configuración de Claude Desktop

Agregue el servidor a su configuración de Claude Desktop:

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

{
  "mcpServers": {
    "cakemail": {
      "command": "node",
      "args": ["/absolute/path/to/cakemail-mcp-server/build/index.js"],
      "env": {
        "CAKEMAIL_USERNAME": "your-email@example.com",
        "CAKEMAIL_PASSWORD": "your-password"
      }
    }
  }
}

🧪 Pruebas

Prueba Rápida

npm run test

Depuración con MCP Inspector

npm run inspector

Verificación de Salud

En Claude Desktop: "Check my Cakemail API health status"

💡 Ejemplos de Uso

Verificación Rápida de Campañas

"Show me my latest campaigns with analytics"

Información de Cuenta

"Show me my account details"

"What's my current retry configuration?"

Gestión de Sub-Cuentas

"Create a new sub-account for our client 'Acme Corp' with the email admin@acmecorp.com"

"List all active sub-accounts and show their verification status"

"Suspend the sub-account for client XYZ temporarily"

"Convert sub-account 12345 to an organization"

Ejemplos de Gestión de Listas

"Create a new contact list called 'Newsletter Subscribers' with our marketing team as the default sender"

"Show me all my contact lists with their subscriber counts"

"Get performance statistics for my main newsletter list"

"Archive the old product launch list but keep the data"

"Update the sender information for my customer list"

Operaciones con Plantillas

"List all my email templates sorted by creation date"

"Create a new template called 'Welcome Email' with modern content structure"

"Get the details of template ID 123 including its content and metadata"

"Update my newsletter template with new HTML content and add marketing tags"

"Duplicate the welcome email template as 'Welcome Email - French'"

"Show me a preview of template 456 by rendering it to HTML"

"Delete the old product launch template that's no longer needed"

"Find all templates tagged with 'newsletter' that I own"

Crear y Enviar Campañas

"Create a new email campaign called 'Holiday Sale 2024' with the subject 'Save 50% on Everything!' and send it to my newsletter list"

Plantillas BEEeditor

"Create a BEE newsletter template with sections for product announcements and customer testimonials"

"Generate a basic BEE template for welcome emails with our brand colors"

"Validate my custom BEE template and show me the structure"

"Create a campaign using BEE format with a professional newsletter layout"

Correos Transaccionales

"Send a transactional welcome email to sara@example.com with our onboarding template"

Operaciones con Listas

"List all my contact lists sorted by creation date"

"Create a contact list for VIP customers with webhook notifications"

"Show me the performance stats for list ID 12345 over the last month"

"Archive all lists that have zero subscribers"

Análisis Avanzado y Exportaciones

"Show me the performance metrics for my latest campaign including open rates and click rates"

"Create a CSV export of all my campaign performance data for the last quarter"

"Get detailed campaign logs for campaign 12345 with advanced sequence analysis to see the complete user journey"

"Analyze campaign 789 logs to identify drop-off points and get optimization recommendations"

"Export the performance data for all my campaigns this year in Excel format"

"Show me link performance analysis for my newsletter campaign with categorization insights"

"Generate performance benchmarks comparing my open rates to industry standards"

Arquitectura del Módulo de Informes

La funcionalidad de informes se basa en una arquitectura modular para una mejor mantenibilidad:

Análisis de Campañas: Información de rendimiento, análisis de enlaces, métricas de participación
Estadísticas de Correos: Rendimiento de correos transaccionales y seguimiento de entregas
Análisis de Listas y Cuentas: Métricas de crecimiento, análisis de suscriptores, salud de cuentas
Gestión de Exportaciones: Ciclo de vida completo de exportaciones con seguimiento de progreso
Motor de Información Inteligente: Análisis automatizado de rendimiento y recomendaciones
Utilidades de Depuración: Pruebas de conectividad de API y resolución de problemas

Cada módulo proporciona funcionalidad enfocada mientras comparte utilidades analíticas comunes para una evaluación comparativa de rendimiento consistente y recomendaciones inteligentes.

🔧 Configuración Avanzada

Reintentos y Limitación de Velocidad

El servidor incluye funcionalidades listas para producción:

Reintento Automático: Retroceso exponencial con fluctuación
Limitación de Velocidad: Respeta los límites de API y las respuestas del servidor
Interruptor de Circuito: Detección automática de fallos y recuperación
Cola de Solicitudes: Control de concurrencia para operaciones por lotes

Manejo de Errores

Tipos de error integrales con mensajes detallados:

Errores de Autenticación: Orientación clara sobre credenciales
Errores de Validación: Detalles de errores específicos por campo
Errores de Límite de Velocidad: Tiempo de reintento automático
Errores de Red: Manejo de conexión y tiempo de espera

🐛 Solución de Problemas

Problemas Comunes

Errores de Autenticación:

Verifique CAKEMAIL_USERNAME y CAKEMAIL_PASSWORD
Asegúrese de que el acceso a API esté habilitado en su cuenta

Errores de Compilación:

npm run clean && npm run rebuild

Nuevas Herramientas No Visibles:

Reinicie Claude Desktop por completo
Espere la carga completa y luego pruebe nuevos comandos

Conectividad de API:

# Test in Claude Desktop
"Check my Cakemail API connection"

Modo de Depuración

DEBUG=mcp:* npm start

🔐 Seguridad

Autenticación OAuth 2.0 con renovación automática de tokens
Validación de entrada para prevenir ataques de inyección
Almacenamiento seguro de credenciales mediante variables de entorno
Limitación de velocidad para prevenir abusos
Comunicación API solo HTTPS

⚠️ Aviso Importante de Seguridad

¡Nunca confíe credenciales al control de versiones! Utilice siempre variables de entorno para datos sensibles:

Copie .env.example a .env
Agregue sus credenciales reales a .env
Asegúrese de que .env esté listado en .gitignore (ya configurado)
Si las credenciales se exponen accidentalmente, rótelas inmediatamente en su cuenta de Cakemail

📚 Soporte

API de Cakemail: https://cakemail.dev
Guía de Gestión de Listas: docs/list-management.md
Integración con BEEeditor: docs/BEE_EDITOR_INTEGRATION.md
Protocolo MCP: https://github.com/modelcontextprotocol
Problemas: https://github.com/cakemail/cakemail-mcp-server/issues

📝 Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulte el archivo LICENSE para más detalles.

¿Listo para mejorar su marketing por correo electrónico con IA? ¡Comience con el Servidor MCP de Cakemail hoy! 🚀