Mailchimp MCP

Servidor MCP de Mailchimp

El servidor Model Context Protocol (MCP) más completo para la Mailchimp Marketing API: 227 herramientas para consultar y gestionar tu cuenta de Mailchimp desde cualquier cliente compatible con MCP. Cubre toda la superficie de campañas, audiencias, miembros, segmentos, automatizaciones e informes, e-commerce completo (lectura y escritura), páginas de aterrizaje, Administrador de archivos, encuestas, formularios de registro y dominios verificados, además de soporte multi-cuenta y protecciones de seguridad en tiempo de ejecución (modos de solo lectura, prueba y auditoría, con metadatos de riesgo por herramienta).

Utiliza la Mailchimp Marketing API a través de requests. No está basado en el cliente oficial mailchimp-marketing-python. Encontré demasiados problemas con él, así que opté por llamadas HTTP directas.

Inicio rápido

uvx mailchimp-mcp   # no install required; just needs MAILCHIMP_API_KEY

Añádelo a tu cliente MCP (Claude Desktop, Cursor, Cline, …):

{
  "mcpServers": {
    "mailchimp": {
      "command": "uvx",
      "args": ["mailchimp-mcp"],
      "env": {
        "MAILCHIMP_API_KEY": "your-key-us8",
        "MAILCHIMP_READ_ONLY": "true"
      }
    }
  }
}

Consejo: comienza con MAILCHIMP_READ_ONLY=true para explorar de forma segura, luego desactívalo cuando estés listo para escribir. Consulta Configuración para todas las opciones.

Docker

Una imagen precompilada se publica en el Registro de Contenedores de GitHub en cada versión:

docker run --rm -i -e MAILCHIMP_API_KEY=your-key-us8 ghcr.io/damientilman/mailchimp-mcp-server:latest

O apunta tu cliente MCP a ella:

{
  "mcpServers": {
    "mailchimp": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "MAILCHIMP_API_KEY", "-e", "MAILCHIMP_READ_ONLY", "ghcr.io/damientilman/mailchimp-mcp-server:latest"],
      "env": {
        "MAILCHIMP_API_KEY": "your-key-us8",
        "MAILCHIMP_READ_ONLY": "true"
      }
    }
  }
}

Características

Lectura

• Campañas - Listar, buscar e inspeccionar detalles de campañas
• Informes - Tasas de apertura/clics, rebotes, clics por enlace, rendimiento por dominio, detalles de cancelaciones de suscripción
• Actividad de correo electrónico - Seguimiento de aperturas/clics por destinatario, historial de actividad de miembros
• Audiencias - Explorar audiencias, miembros, segmentos, etiquetas e historial de crecimiento
• Campos de combinación - Listar campos personalizados para una audiencia
• Categorías y grupos de interés - Explorar categorías de interés y opciones
• Webhooks - Listar webhooks configurados
• Segmentos - Obtener detalles de segmentos, condiciones y listas de miembros
• Automatizaciones - Listar flujos de trabajo, inspeccionar correos electrónicos en un flujo de trabajo, ver colas
• Plantillas - Explorar plantillas y extraer contenido HTML
• Páginas de aterrizaje - Listar e inspeccionar páginas de aterrizaje
• Administrador de archivos - Explorar imágenes y archivos almacenados, y carpetas
• Encuestas - Listar e inspeccionar encuestas de una audiencia
• Formularios de registro - Inspeccionar formularios de registro de una audiencia
• E-commerce - Tiendas, pedidos, productos, clientes (requiere integración de e-commerce)
• Carpetas de campañas - Explorar la organización de carpetas
• Operaciones por lotes - Monitorear el estado de operaciones masivas

Escritura

• Miembros - Añadir, actualizar, cancelar suscripción, eliminar y etiquetar contactos
• Audiencias - Suscripción masiva de miembros, actualizar configuraciones de audiencia
• Campañas - Crear borradores, establecer contenido HTML, programar, desprogramar, duplicar, eliminar, enviar, enviar prueba, cancelar
• Segmentos/Etiquetas - Crear, actualizar, eliminar, añadir/eliminar miembros, condiciones dinámicas
• Campos de combinación - Crear, actualizar, eliminar campos personalizados
• Categorías de interés - Crear y eliminar categorías e intereses
• Webhooks - Crear y eliminar webhooks
• Plantillas - Crear, actualizar y eliminar plantillas de correo electrónico
• Administrador de archivos - Subir (base64) y eliminar imágenes y archivos
• Encuestas - Publicar y despublicar encuestas de audiencia
• Formularios de registro - Personalizar encabezado, contenidos y estilos
• Automatizaciones - Pausar e iniciar flujos de trabajo de automatización
• E-commerce - Ciclo de vida del carrito, reglas promocionales y códigos promocionales para flujos de descuento
• Lote - Ejecutar operaciones API masivas en una sola solicitud

Seguridad en tiempo de ejecución

• Metadatos de riesgo - Clasificación por herramienta de lectura / escritura / destructiva mediante anotaciones MCP y describe_tools
• Registro de auditoría - Eventos de auditoría JSON estructurados opcionales por despacho (MAILCHIMP_AUDIT_LOG)
• Validación de argumentos - Límites de paginación y verificaciones de ID requeridos antes de cada solicitud

Requisitos previos

• Python 3.10+
• Una clave API de Mailchimp

Instalación

Usando uvx (recomendado)

No se necesita instalación — ejecuta directamente:

uvx mailchimp-mcp

Usando pip

pip install mailchimp-mcp

Luego ejecuta:

mailchimp-mcp

Desde el código fuente

git clone https://github.com/damientilman/mailchimp-mcp-server.git
cd mailchimp-mcp-server
python -m venv .venv
source .venv/bin/activate
pip install -e .

Configuración

El centro de datos (us8, us21, etc.) se extrae automáticamente de cada clave.

Modos de seguridad

Modo de solo lectura — Cuando MAILCHIMP_READ_ONLY=true, todas las herramientas de escritura (crear, actualizar, eliminar, programar, etc.) están bloqueadas y devuelven un error. Las herramientas de lectura funcionan normalmente. Este es el predeterminado recomendado para configuraciones compartidas o exploratorias donde solo necesitas informes y análisis.

Modo de prueba — Cuando MAILCHIMP_DRY_RUN=true, las herramientas de escritura devuelven una vista previa de la acción que harían (nombre de la herramienta, recurso objetivo, parámetros y su nivel de riesgo) sin realizar ninguna llamada API. Útil para probar indicaciones antes de entrar en producción.

Seguridad en tiempo de ejecución

El servidor está diseñado para defensa en profundidad junto con una puerta de enlace MCP externa: posee la semántica (qué herramientas son lecturas, escrituras reversibles o irreversibles) y las expone como señales legibles por máquina que una puerta de enlace puede aplicar, en lugar de hacer que la puerta de enlace adivine qué llamadas son peligrosas.

Metadatos de riesgo — Cada herramienta se clasifica como read, write o destructive (pérdida de datos irreversible o envío irreversible). Esto se muestra de dos maneras:

• Anotaciones de herramientas MCP — readOnlyHint, destructiveHint y idempotentHint viajan a través del tools/list estándar, por lo que cualquier cliente o puerta de enlace compatible los lee directamente.
• describe_tools — una herramienta de lectura que devuelve {name, risk, read_only, destructive, idempotent} para cada herramienta más recuentos por nivel, para puertas de enlace que prefieren una llamada de herramienta.

Registro de auditoría estructurado — Con MAILCHIMP_AUDIT_LOG=true, cada despacho emite un evento JSON a stderr con la herramienta, su nivel de riesgo, la bandera destructive, la cuenta objetivo, el resultado (executed / blocked_read_only / dry_run) y los argumentos inspeccionados. Los valores voluminosos o sensibles (ej. file_data base64) se redactan y los cuerpos de respuesta nunca se registran, por lo que el flujo es un sumidero de auditoría seguro para rastrear centralmente.

Validación de contrato de argumentos — Todas las escrituras pasan por un único punto de control _guard_write, y cada solicitud se valida antes del despacho (paginación count limitada a 1–1000, IDs de ruta faltantes rechazados), por lo que las llamadas malformadas fallan rápido y de manera consistente en lugar de llegar a la API.

Perfiles de herramientas

Exponer las 227 herramientas envía una lista grande de herramientas al modelo en cada turno (~63k tokens). Si solo necesitas parte de la superficie, carga un subconjunto con una línea:

"env": { "MAILCHIMP_API_KEY": "your-key-us8", "MAILCHIMP_TOOLS": "read" }

MAILCHIMP_TOOLS acepta una mezcla separada por comas de niveles de riesgo (read, write, destructive) y/o nombres exactos de herramientas; una herramienta se conserva si cualquiera coincide. Sin establecer (o all) expone todo.

• read — solo informes y análisis (~115 herramientas, ~29k tokens). Un predeterminado seguro y ligero para exploración.
• read,write — todo excepto herramientas irreversibles.
• list_campaigns,get_campaign_report,send_campaign — un conjunto mínimo seleccionado a mano.

Las descripciones de herramientas también se recortan de texto repetitivo antes de llegar al modelo, por lo que incluso el conjunto completo es más ligero que las cadenas de documentación crudas. Usa describe_tools para ver el nivel de riesgo de cada herramienta.

Multi-cuenta

Por predeterminado, el servidor usa el único MAILCHIMP_API_KEY, expuesto como la cuenta default. Para gestionar varias cuentas de Mailchimp desde un servidor, añade variables MAILCHIMP_API_KEY_<NAME> — el sufijo se convierte en el nombre de cuenta en minúsculas (ej. MAILCHIMP_API_KEY_MARKETING → marketing).

Cada herramienta acepta entonces un argumento opcional account, ej. list_audiences(account="marketing"). La selección es por llamada y sin estado — no hay "cuenta actual" para cambiar, por lo que una escritura siempre nombra su objetivo. Omitir account usa default. Llama a list_accounts para ver los nombres configurados y su estado de bandera de seguridad, y cada cuenta puede llevar sus propias banderas MAILCHIMP_READ_ONLY_<NAME> / MAILCHIMP_DRY_RUN_<NAME> (para que una cuenta protegida contra escritura y una escribible puedan coexistir). Un account desconocido devuelve un error que lista los nombres configurados.

Las configuraciones de clave única no se ven afectadas: con solo MAILCHIMP_API_KEY establecido, nada cambia.

{
  "mcpServers": {
    "mailchimp": {
      "command": "uvx",
      "args": ["mailchimp-mcp"],
      "env": {
        "MAILCHIMP_API_KEY": "your-default-key-us8",
        "MAILCHIMP_API_KEY_MARKETING": "another-key-us5",
        "MAILCHIMP_READ_ONLY_MARKETING": "true"
      }
    }
  }
}

Configuración del cliente MCP

La mayoría de los clientes MCP aceptan un bloque de configuración JSON que describe cómo lanzar el servidor. Configura el tuyo para invocar uvx mailchimp-mcp (o mailchimp-mcp si está instalado vía pip) con MAILCHIMP_API_KEY exportado en el entorno.

{
  "mcpServers": {
    "mailchimp": {
      "command": "uvx",
      "args": ["mailchimp-mcp"],
      "env": {
        "MAILCHIMP_API_KEY": "your-api-key-here"
      }
    }
  }
}

{
  "mcpServers": {
    "mailchimp": {
      "command": "mailchimp-mcp",
      "env": {
        "MAILCHIMP_API_KEY": "your-api-key-here"
      }
    }
  }
}

{
  "mcpServers": {
    "mailchimp": {
      "command": "uvx",
      "args": ["mailchimp-mcp"],
      "env": {
        "MAILCHIMP_API_KEY": "your-api-key-here",
        "MAILCHIMP_READ_ONLY": "true"
      }
    }
  }
}

Clientes basados en CLI

Si tu cliente MCP proporciona una CLI para registrar servidores, la invocación equivalente es:

mcp-cli add mailchimp \
  -e MAILCHIMP_API_KEY=your-api-key-here \
  -- uvx mailchimp-mcp

Reemplaza mcp-cli con el nombre del binario de tu cliente. Para el modo de solo lectura, añade -e MAILCHIMP_READ_ONLY=true al comando.

Herramientas disponibles

Cuenta

Campañas (lectura)

Informes de campañas

Campañas (escritura)

Audiencias (lectura)

Miembros (lectura)

Miembros (escritura)

Audiencias (escritura)

Segmentos y etiquetas

Campos de combinación

Categorías de interés y grupos

Webhooks

Automatizaciones y Customer Journeys

Mailchimp no expone una API de lectura pública para Customer Journeys (solo el endpoint de activación anterior). Las herramientas search_automation_campaigns, get_member_journey_events y get_automation_summary proporcionan las soluciones alternativas recomendadas: muestran todas las campañas emitidas por automatizaciones o journeys, aunque el grafo del journey en sí permanezca privado.

Plantillas

Páginas de destino

Administrador de archivos

Encuestas

Formularios de suscripción

Comercio electrónico

Carritos de comercio electrónico

Reglas y códigos promocionales de comercio electrónico

Operaciones por lotes

Dominios verificados

Sitios conectados y cuenta

Carpetas

Extras de campaña (lista de verificación, colaboración, RSS)

Información de audiencia y entregabilidad

Miembros (cumplimiento y avanzado)

Correos de automatización (control de un solo correo)

Informes (extras)

Comercio electrónico (escritura)

Ejemplos de solicitudes

Una vez conectado, puedes pedirle a tu cliente MCP que realice solicitudes como:

• "Muéstrame todas mis campañas enviadas de los últimos 3 meses"
• "¿Cuál fue la tasa de apertura y la tasa de clics de mi último boletín?"
• "¿Cuántos suscriptores gané este año?"
• "¿Qué enlaces recibieron más clics en la campaña X?"
• "Buscar al suscriptor john@example.com"
• "Añade la etiqueta 'VIP' a todos los miembros que abrieron mi última campaña"
• "Crea un borrador de campaña para mi audiencia principal con el asunto 'March Update'"
• "Crea una campaña dirigida solo a mi segmento VIP"
• "Envía un correo de prueba de mi borrador de campaña a test@example.com"
• "Lista todos los campos de combinación de mi audiencia principal"
• "Crea un campo de combinación desplegable llamado 'Industry' con opciones Tech, Finance, Healthcare"
• "Crea un segmento dinámico de miembros donde FNAME sea John"
• "Suscribe en lote a 50 miembros de estos datos CSV"
• "Configura un webhook para notificar a mi aplicación cuando se unan nuevos suscriptores"
• "Da de baja a user@example.com de mi lista"
• "Muéstrame el desglose de rendimiento por dominio de mi última campaña"
• "¿Dónde en el mundo abrieron mi boletín? Muéstrame el desglose geográfico."
• "Crea una campaña de prueba A/B con dos líneas de asunto y elige la ganadora por aperturas después de 24 horas"
• "¿Qué consejos tiene Mailchimp para mejorar mi última campaña?"
• "Pausa mi automatización de bienvenida"
• "Lista todos los pedidos de mi tienda Shopify este mes"

Recetas de flujo de trabajo

Solicitudes de varios pasos que encadenan herramientas de principio a fin:

• Revisión de rendimiento semanal — "Resume mi última semana: lista las campañas enviadas desde el lunes, extrae cada informe y clasifícalas por tasa de clics con una conclusión para cada una." Encadena search_campaigns → get_campaign_report → get_campaign_advice.
• Auditoría de entregabilidad — "Comprueba mi salud de envío: ¿están verificados mis dominios, hay quejas de spam en campañas recientes y cómo le fue a la última por dominio de destinatario?" Encadena list_verified_domains → get_campaign_abuse_reports → get_domain_performance.
• Re-enganche — "Encuentra a todos los que no abrieron mi último boletín y reenvíalo con una nueva línea de asunto." Encadena get_campaign_report → resend_to_non_openers.
• Envío seguro — "Haz una prueba en seco de una campaña para mi segmento VIP, muéstrame la lista de verificación de envío y luego envíala cuando confirme." Con MAILCHIMP_DRY_RUN=true, vistas previas mediante create_campaign → get_campaign_send_checklist → send_campaign.
• Agencias (multi-cuenta) — "Para las cuentas acme y globex, lista la mejor campaña de este mes por tasa de apertura." Pasa account="acme" / account="globex" por llamada. Consulta Multi-cuenta.

Contribuciones

Las contribuciones son bienvenidas. Consulta CONTRIBUTING.md para la configuración de desarrollo, las instrucciones de prueba y las pautas de solicitudes de extracción.

Seguridad

Si encuentras una vulnerabilidad de seguridad, sigue el proceso de divulgación responsable descrito en SECURITY.md.

Registro de cambios

Consulta CHANGELOG.md para el historial completo de versiones.

Autor

Creado por Damien Tilman — damien@tilman.marketing

Licencia

MIT — consulta LICENSE para más detalles.