@cyanheads/mailchimp-mcp-server

Herramientas

Dieciocho herramientas siempre activas más dos condicionales — mailchimp_assets (cuando MAILCHIMP_ASSETS_DIR está definido) y mailchimp_local_templates (cuando MAILCHIMP_TEMPLATES_DIR está definido). Los asistentes de flujo de trabajo orquestan flujos comunes de principio a fin, las herramientas primitivas exponen CRUD de grano fino, y la herramienta de instrucción devuelve orientación procedimental combinada con el estado de la cuenta en tiempo real.

mailchimp_send_campaign

Redacta y envía (o programa/prueba) una campaña en una sola llamada.

• Encadena crear → contenido → lista de verificación → prueba opcional → enviar/programar

• Solicita confirmación humana mediante una ronda de entrada reentrante antes de cualquier mutación de campaña cuando mode: 'send' | 'schedule'

• Elimina automáticamente los borradores fallidos cuando cleanupOnError: true (por defecto); la confirmación rechazada deja un borrador revisable

• Admite formularios de contenido html, plaintext, templateId + templateSections y plantillas Eta locales

mailchimp_replicate_campaign

Duplica una campaña existente con anulaciones opcionales y luego envía/programa/prueba o déjala como borrador.

• Anulaciones: asunto, nombre del remitente, responder a, audiencia, segmento, contenido

• Mismas semánticas de confirmación reentrante + limpieza que mailchimp_send_campaign

• Optimizado para el patrón común de "enviar v2 del boletín de la semana pasada con una introducción actualizada"

mailchimp_upsert_subscriber

Añade o actualiza un suscriptor en una sola llamada idempotente.

• Sincronización declarativa de etiquetas — pasa el conjunto activo deseado y la herramienta calcula el delta de añadir/eliminar

• preserveTags protege las membresías de segmentos con nombre (Mailchimp almacena la membresía de segmentos estáticos como etiquetas)

• status: 'pending' activa el correo de doble opt-in de Mailchimp; 'subscribed' requiere consentimiento documentado

• PUT /members/{hash} para la ruta de creación, PATCH para la actualización y omitir la revalidación de campos de combinación preexistentes

mailchimp_import_subscribers

Añade (y opcionalmente actualiza) suscriptores por lotes en una sola llamada.

• Limitado a 500 filas por llamada — divide importaciones más grandes en el lado del cliente

• El estado por defecto es pending (doble opt-in) para evitar envíos masivos accidentales

• Devuelve por fila correcto/fallido con motivos de error

mailchimp_campaign_report

Análisis agregado posterior al envío para una campaña.

• Métricas de entrega principales: enviados, rebotes, informes de abuso

• Interacción: aperturas, clics, bajas

• Enlaces más clicados (Top-N), ubicaciones, bajas recientes

• Referencias del sector cuando estén disponibles

• Usa mailchimp_reports con operation: 'slice' para una sola dimensión en detalle

mailchimp_audience_overview

Resumen de salud de la audiencia en una sola llamada: responde a «¿cómo es esta audiencia?» en una sola petición.

• Información de la audiencia + estadísticas en vivo

• Historial de crecimiento configurable en meses

• Principales clientes de correo

• Esquema completo de campos de combinación

• Actividad reciente

mailchimp_playbook

Devuelve un manual de procedimientos estructurado combinado con el estado en vivo de la cuenta. Solo asesoramiento: el agente ejecuta los pasos posteriores con otras herramientas.

• Temas: send, post-send-review, deliverability, list-hygiene, onboarding, subscriber-triage, design-campaign

• Devuelve instrucciones en markdown + una instantánea del estado en vivo

• nextToolSuggestions rellena previamente los argumentos para la siguiente llamada a herramienta probable

Related MCP server: Mailchimp MCP Server

Recursos y prompts

Todos los datos de los recursos también son accesibles a través de las herramientas. Las colecciones grandes (audiences, campaigns) no se exponen como recursos: usa la operación list en la herramienta correspondiente. Referencia de diseño para el prompt: docs/email-design-playbook.md.

Características

Construido sobre @cyanheads/mcp-ts-core:

• Definiciones declarativas de herramientas, recursos y prompts: un solo archivo por primitiva, el framework gestiona el registro y la validación

• Manejo de errores unificado: los manejadores lanzan excepciones, el framework las captura, clasifica y formatea

• Autenticación conectable: none, jwt, oauth

• Registro estructurado con trazado opcional de OpenTelemetry

• Transportes STDIO y Streamable HTTP

Específico de Mailchimp:

• Deriva automáticamente la URL base de la API a partir del sufijo -dc de la clave de API

• Flujos de envío seguros por defecto: confirmación reentrante, importaciones en estado pendiente, sin eliminaciones permanentes desde la superficie del agente

• Las herramientas de flujo de trabajo paralelizan las subpeticiones relacionadas bajo un límite de concurrencia configurable

• La normalización de dominio transforma las cargas útiles dispersas de upstream en una salida compacta y amigable para LLM sin inventar valores

Primeros pasos

Añade lo siguiente a tu archivo de configuración del cliente MCP. Consulta docs/api-key.md para saber cómo generar una clave de API de Mailchimp.

{
  "mcpServers": {
    "mailchimp-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/mailchimp-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "MAILCHIMP_API_KEY": "your-key-with-dc-suffix-e.g.-us22"
      }
    }
  }
}

O con npx (no se requiere Bun):

{
  "mcpServers": {
    "mailchimp-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/mailchimp-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "MAILCHIMP_API_KEY": "your-key-with-dc-suffix-e.g.-us22"
      }
    }
  }
}

O con Docker:

{
  "mcpServers": {
    "mailchimp-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "MAILCHIMP_API_KEY=your-key-with-dc-suffix-e.g.-us22",
        "ghcr.io/cyanheads/mailchimp-mcp-server:latest"
      ]
    }
  }
}

Para Streamable HTTP, configura el transporte e inicia el servidor:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 MAILCHIMP_API_KEY=... bun run start:http
# Server listens at http://localhost:3010/mcp

Requisitos previos

• Bun v1.4.0 o superior (o Node.js v24+).

• Una clave de API de Mailchimp Marketing: el sufijo -dc de la clave (p. ej. -us22) identifica tu centro de datos y se analiza al inicio.

Instalación

1. Clona el repositorio:

git clone https://github.com/cyanheads/mailchimp-mcp-server.git

2. Accede al directorio:

cd mailchimp-mcp-server

3. Instala las dependencias:

bun install

4. Configura el entorno:

cp .env.example .env
# edit .env and set MAILCHIMP_API_KEY

Configuración

Consulta .env.example para ver la lista completa de sobrescrituras opcionales.

Recursos locales (opcional)

Define MAILCHIMP_ASSETS_DIR para habilitar un flujo de trabajo de imágenes locales sobre Mailchimp File Manager. Coloca los archivos de imagen en el directorio, refiérelos en el HTML como @assets/<relative-path>, y el servidor los sube y reescribe en el momento del envío.

export MAILCHIMP_ASSETS_DIR=/Users/me/Pictures/email-assets

Luego, en una campaña:

<img src="@assets/hero.png" alt="Hero">
<a href="@assets/whitepaper.pdf">Download</a>

Cuando mailchimp_send_campaign (o mailchimp_campaigns set-content / mailchimp_replicate_campaign contentOverride) detecta estas referencias:

1. Calcula el hash (SHA-256) de cada archivo referenciado.

2. Sube los elementos no presentes en la caché a Mailchimp File Manager mediante la superficie de la herramienta mailchimp_files.

3. Almacena en caché sha256 → file_id + URL en <assetsDir>/.mailchimp-cache.json (escrituras atómicas; se puede eliminar sin riesgo para forzar una nueva subida).

4. Reescribe cada @assets/<path> a la URL pública del CDN antes de enviar el contenido a upstream.

La herramienta mailchimp_assets expone list, info, sync (precalentamiento) y clear-cache para inspección directa; la mayoría de los flujos de trabajo no la necesitan.

Advertencias:

• Mailchimp limita las imágenes a 1 MB y el resto de archivos a 10 MB. Los archivos que superen el tamaño fallan antes de la subida con un error procesable.

• Extensiones permitidas: consulta la descripción de la herramienta mailchimp_files. WebP y AVIF NO están en la lista de permitidos: conviértelos a PNG/JPG.

• Se rechaza el path traversal (../ y las rutas absolutas lanzan Forbidden).

• La herramienta mailchimp_assets es solo Node; en Cloudflare Workers no está registrada.

Plantillas locales (opcional)

Define MAILCHIMP_TEMPLATES_DIR para habilitar un flujo de trabajo de creación de plantillas locales sobre Eta (v4: rápido, nativo de ESM, compatible con parciales/condicionales/bucles). Esta es la vía de escritura canónica para plantillas en cuentas gratuitas de Mailchimp, donde la API /templates de upstream es de solo lectura.

export MAILCHIMP_TEMPLATES_DIR=/Users/me/email-templates

email-templates/
  welcome.eta              # body + optional YAML frontmatter
  newsletter.eta
  partials/
    header.eta
    footer.eta

Plantilla (welcome.eta): frontmatter YAML arriba, cuerpo Eta debajo:

---
subject: "Welcome to {{brand}}"
previewText: "Onboarding starts here"
vars:
  - firstName
  - brand
---
<%~ include('partials/header', it) %>
<h1>Hello <%= it.firstName %></h1>
<p>Welcome to <%= it.brand %>.</p>
<img src="@assets/hero.png" alt="Hero">

Frontmatter es opcional — un cuerpo sin bloque --- se trata como una plantilla sin metadatos. Todos los campos de metadatos también son opcionales. La lista vars: es solo informativa (las variables declaradas no están sujetas al esquema).

Respaldo sidecar (heredado): antes de v0.3.1, los metadatos se encontraban en un archivo <name>.meta.yaml separado junto al cuerpo. Esa forma sigue funcionando por compatibilidad hacia atrás — si un .eta no tiene frontmatter, el cargador recurre a leer el sidecar. El frontmatter tiene prioridad cuando ambos existen.

Referencia desde cualquier herramienta de campaña:

{
  "audienceId": "abc123",
  "subject": "Welcome to Acme",
  "fromName": "Casey",
  "replyTo": "casey@acme.com",
  "content": {
    "localTemplate": "welcome",
    "localTemplateVars": { "firstName": "Sam", "brand": "Acme" }
  },
  "mode": "draft"
}

El pipeline de renderizado:

1. Eta renderiza welcome.eta con it = { firstName: 'Sam', brand: 'Acme' }.

2. Si L1 está configurado, @assets/hero.png se sube al Administrador de archivos de Mailchimp y se reescribe a una URL de CDN.

3. El HTML final se establece en la campaña mediante set-content de Mailchimp.

La herramienta mailchimp_local_templates expone list, get, render-preview (devuelve HTML sin enviar) y seed-from-mailchimp (lee una plantilla base/user de Mailchimp por ID y la escribe en disco como punto de partida — útil en el plan gratuito, donde puedes leer pero no escribir upstream).

Plantillas de ejemplo en este repositorio

El directorio templates/ contiene ejemplos funcionales — apunta MAILCHIMP_TEMPLATES_DIR directamente a él para probarlos, o cópialos a tu propio directorio como punto de partida:

Advertencias:

• localTemplate es mutuamente excluyente con html y templateId en el mismo bloque de contenido.

• La validación de variables no está impuesta por el esquema — las variables faltantes o sobrantes aparecen como errores de renderizado de Eta en el momento del envío.

• Se rechaza el path traversal.

• Solo Node; no disponible en Workers.

Ejecutar el servidor

Desarrollo local

• Modo watch (transporte mediante MCP_TRANSPORT_TYPE):

  bun run dev                                     # stdio (default)
  MCP_TRANSPORT_TYPE=http bun run dev             # http

• Compilar y ejecutar:

  bun run rebuild
  bun run start:stdio
  # or
  bun run start:http

• Ejecutar comprobaciones y pruebas:

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec

Docker

docker build -t mailchimp-mcp-server .
docker run --rm -e MAILCHIMP_API_KEY=your-key-us22 -p 3010:3010 mailchimp-mcp-server

El Dockerfile usa por defecto transporte HTTP, modo de sesión sin estado y registra en /var/log/mailchimp-mcp-server. Las dependencias pares de OpenTelemetry se instalan por defecto — compila con --build-arg OTEL_ENABLED=false para omitirlas.

Estructura del proyecto

Guía de desarrollo

Consulta CLAUDE.md para las pautas de desarrollo y las reglas arquitectónicas. La versión corta:

• Los handlers lanzan excepciones, el framework las captura — no uses try/catch en la lógica de las herramientas.

• Usa ctx.log para el registro con ámbito de solicitud.

• Registra nuevas herramientas y recursos mediante los barrels en src/mcp-server/*/definitions/index.ts.

• Envuelve las llamadas a API externas: valida el dato bruto → normaliza al tipo de dominio → devuelve el esquema de salida; nunca inventes campos faltantes.

Contribuciones

Las issues y los pull requests son bienvenidos. Ejecuta las comprobaciones y las pruebas antes de enviar:

bun run devcheck
bun run test

Licencia

Este proyecto está licenciado bajo la Licencia Apache 2.0. Consulta el archivo LICENSE para más detalles.