@cyanheads/mailchimp-mcp-server

Tools

Achtzehn dauerhaft verfügbare Tools plus zwei bedingte — mailchimp_assets (wenn MAILCHIMP_ASSETS_DIR gesetzt ist) und mailchimp_local_templates (wenn MAILCHIMP_TEMPLATES_DIR gesetzt ist). Workflow-Helfer orchestrieren gängige Abläufe end-to-end, grundlegende Tools bieten feingranulares CRUD, und das Instruction-Tool liefert prozedurale Anleitungen, kombiniert mit dem Live-Kontostand.

mailchimp_send_campaign

Verfasse und sende (oder plane/teste) eine Kampagne in einem Aufruf.

• Verkettet Erstellen → Inhalt → Checkliste → optionalen Test → Senden/Planen

• Fordert eine menschliche Bestätigung über eine re-entrante Eingaberunde an, bevor bei mode: 'send' | 'schedule' eine Kampagnen-Mutation durchgeführt wird

• Löscht fehlgeschlagene Entwürfe automatisch, wenn cleanupOnError: true (Standard); abgelehnte Bestätigung hinterlässt einen überprüfbaren Entwurf

• Unterstützt html, plaintext, templateId + templateSections und lokale Eta-Template-Inhaltsformen

mailchimp_replicate_campaign

Dupliziere eine bestehende Kampagne mit optionalen Overrides und sende/plane/teste sie oder lasse sie als Entwurf.

• Overrides: Betreff, Absendername, Antwort-an, Zielgruppe, Segment, Inhalt

• Gleiche re-entrante Bestätigungs- und Bereinigungssemantik wie mailchimp_send_campaign

• Optimiert für das häufige Muster „v2 des Newsletters von letzter Woche mit aktualisierter Einleitung senden“

mailchimp_upsert_subscriber

Füge einen Abonnenten in einem idempotenten Aufruf hinzu oder aktualisiere ihn.

• Deklarative Tag-Synchronisierung — übergib den gewünschten aktiven Satz und das Tool berechnet das Hinzufügen/Entfernen-Delta

• preserveTags schützt benannte Segment-Mitgliedschaften (Mailchimp speichert die Mitgliedschaft in statischen Segmenten als Tags)

• status: 'pending' löst Mailchimps Double-Opt-in-E-Mail aus; 'subscribed' erfordert dokumentierte Einwilligung

• PUT /members/{hash} für den Erstellungspfad, PATCH für die Aktualisierung, um die erneute Validierung vorhandener Merge-Felder zu überspringen

mailchimp_import_subscribers

Füge Abonnenten stapelweise hinzu (und aktualisiere sie optional) in einem Aufruf.

• Begrenzt auf 500 Zeilen pro Aufruf — größere Importe clientseitig aufteilen

• Status ist standardmäßig pending (Double-Opt-in), um versehentliche Massenversendungen zu verhindern

• Gibt pro Zeile Erfolg/Fehler mit Fehlergründen zurück

mailchimp_campaign_report

Aggregierte Analysen nach dem Versand für eine Kampagne.

• Headline delivery metrics: sent, bounces, abuse reports

• Engagement: opens, clicks, unsubscribes

• Top-N clicked links, locations, recent unsubscribes

• Industry benchmarks when available

• Use mailchimp_reports with operation: 'slice' for a single dimension in detail

mailchimp_audience_overview

Single-call audience health digest — answers "what does this audience look like?" in one request.

• Audience info + live stats

• Configurable months of growth history

• Top email clients

• Full merge-field schema

• Recent activity

mailchimp_playbook

Returns a structured procedural playbook merged with live account state. Advice-only — the agent executes subsequent steps with other tools.

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

• Returns markdown instructions + a live-state snapshot

• nextToolSuggestions pre-fills arguments for the next likely tool call

Related MCP server: Mailchimp MCP Server

Ressourcen und Prompts

Alle Ressourcendaten sind auch über Tools erreichbar. Große Sammlungen (audiences, campaigns) werden nicht als Ressourcen bereitgestellt – verwenden Sie stattdessen die list-Operation des entsprechenden Tools. Design-Referenz für den Prompt: docs/email-design-playbook.md.

Funktionen

Basiert auf @cyanheads/mcp-ts-core:

• Deklarative Tool-, Ressourcen- und Prompt-Definitionen – eine Datei pro Primitive, das Framework übernimmt Registrierung und Validierung

• Einheitliche Fehlerbehandlung – Handler werfen, das Framework fängt, klassifiziert und formatiert

• Plug-in-fähige Authentifizierung: none, jwt, oauth

• Strukturierte Protokollierung mit optionalem OpenTelemetry-Tracing

• STDIO- und Streamable-HTTP-Transports

Mailchimp-spezifisch:

• Leitet die API-Basis-URL automatisch aus dem -dc-Suffix des API-Schlüssels ab

• Standardmäßig sichere Send-Workflows – wiederholbare Bestätigung, Imports mit ausstehendem Status, keine dauerhaften Löschungen über die Agent-Oberfläche

• Workflow-Tools parallelisieren zusammengehörige Unteranfragen unter einem konfigurierbaren Parallelitätslimit

• Domain-Normalisierung formt spärliche Upstream-Payloads in kompakte, LLM-freundliche Ausgaben um, ohne Werte zu erfinden

Erste Schritte

Fügen Sie Folgendes zu Ihrer MCP-Client-Konfigurationsdatei hinzu. Informationen zum Generieren eines Mailchimp-API-Schlüssels finden Sie in docs/api-key.md.

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

Oder mit npx (kein Bun erforderlich):

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

Oder mit 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"
      ]
    }
  }
}

Für Streamable HTTP legen Sie den Transport fest und starten Sie den Server:

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

Voraussetzungen

• Bun v1.4.0 oder höher (oder Node.js v24+).

• Ein Mailchimp-Marketing-API-Schlüssel – das -dc-Suffix des Schlüssels (z. B. -us22) identifiziert Ihr Rechenzentrum und wird beim Start geparst.

Installation

1. Klonen Sie das Repository:

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

2. Wechseln Sie in das Verzeichnis:

cd mailchimp-mcp-server

3. Installieren Sie die Abhängigkeiten:

bun install

4. Konfigurieren Sie die Umgebung:

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

Konfiguration

Siehe .env.example für die vollständige Liste der optionalen Überschreibungen.

Lokale Assets (optional)

Setzen Sie MAILCHIMP_ASSETS_DIR, um einen lokalen Bild-Workflow auf Basis des Mailchimp File Managers zu aktivieren. Legen Sie Bilddateien in das Verzeichnis, referenzieren Sie sie im HTML als @assets/<relative-path>, und der Server lädt sie zum Sendezeitpunkt hoch und schreibt sie um.

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

Dann in einer Kampagne:

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

Wenn mailchimp_send_campaign (oder mailchimp_campaigns set-content / mailchimp_replicate_campaign contentOverride) diese Referenzen sieht, geht es wie folgt vor:

1. Hasht jede referenzierte Datei (SHA-256).

2. Lädt Cache-Misses über die mailchimp_files-Tool-Oberfläche in den Mailchimp File Manager hoch.

3. Speichert sha256 → file_id + URL unter <assetsDir>/.mailchimp-cache.json (atomare Schreibvorgänge; kann bedenkenlos gelöscht werden, um einen erneuten Upload zu erzwingen).

4. Schreibt jedes @assets/<path> vor der Weitergabe an Upstream in die öffentliche CDN-URL um.

Das mailchimp_assets-Tool stellt list, info, sync (Pre-Warm) und clear-cache zur direkten Überprüfung bereit – die meisten Workflows benötigen es nicht.

Einschränkungen:

• Mailchimp begrenzt Bilder auf 1 MB und andere Dateien auf 10 MB. Zu große Dateien schlagen vor dem Upload mit einer umsetzbaren Fehlermeldung fehl.

• Zulässige Erweiterungen: siehe Beschreibung des mailchimp_files-Tools. WebP und AVIF sind NICHT in der Zulassungsliste – konvertieren Sie sie in PNG/JPG.

• Pfad-Traversal wird abgelehnt (../ und absolute Pfade werfen Forbidden).

• Das mailchimp_assets-Tool ist nur für Node; auf Cloudflare Workers ist es nicht registriert.

Lokale Templates (optional)

Setzen Sie MAILCHIMP_TEMPLATES_DIR, um einen Workflow zum Erstellen lokaler Templates auf Basis von Eta zu aktivieren (v4 – schnell, ESM-nativ, unterstützt Partials/Konditionale/Schleifen). Dies ist der kanonische Schreibpfad für Templates auf Mailchimp-Konten im kostenlosen Tarif, bei denen die Upstream-/templates-API schreibgeschützt ist.

export MAILCHIMP_TEMPLATES_DIR=/Users/me/email-templates

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

Template (welcome.eta) – YAML-Frontmatter oben, Eta-Body darunter:

---
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 ist optional — ein Body ohne ----Block wird als Template ohne Meta behandelt. Auch alle Meta-Felder sind optional. Die vars:-Liste ist rein informativ (deklarierte Variablen werden nicht vom Schema erzwungen).

Sidecar-Fallback (Legacy): vor v0.3.1 befanden sich die Meta-Daten in einer separaten <name>.meta.yaml-Datei neben dem Body. Diese Form funktioniert weiterhin aus Gründen der Abwärtskompatibilität — wenn eine .eta-Datei kein Frontmatter hat, greift der Loader auf das Lesen des Sidecars zurück. Wenn beides existiert, hat das Frontmatter Vorrang.

Referenz aus jedem Kampagnen-Tool:

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

Die Render-Pipeline:

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

2. Wenn L1 konfiguriert ist, wird @assets/hero.png in den Mailchimp File Manager hochgeladen und in eine CDN-URL umgeschrieben.

3. Das finale HTML wird über Mailchimp's set-content auf der Kampagne gesetzt.

Das Tool mailchimp_local_templates stellt list, get, render-preview (gibt HTML zurück, ohne zu senden) und seed-from-mailchimp bereit (liest ein base/user-Template von Mailchimp anhand der ID und schreibt es als Ausgangspunkt auf die Festplatte — nützlich im Free-Tarif, wenn man upstream lesen, aber nicht schreiben kann).

Beispiel-Templates in diesem Repository

Das Verzeichnis templates/ enthält funktionierende Beispiele — setze MAILCHIMP_TEMPLATES_DIR direkt darauf, um sie auszuprobieren, oder kopiere sie als Ausgangspunkt in dein eigenes Verzeichnis:

Einschränkungen:

• localTemplate schließt sich mit html und templateId im selben Content-Block gegenseitig aus.

• Die Var-Validierung wird nicht vom Schema erzwungen — fehlende/überzählige Vars treten zur Sendezeit als Eta-Renderfehler auf.

• Path-Traversal wird abgelehnt.

• Nur Node; nicht auf Workers verfügbar.

Den Server ausführen

Lokale Entwicklung

• Watch-Modus (Transport über MCP_TRANSPORT_TYPE):

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

• Bauen und ausführen:

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

• Checks und Tests ausführen:

  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

Das Dockerfile ist standardmäßig auf HTTP-Transport und zustandslosen Session-Modus ausgelegt und schreibt Logs nach /var/log/mailchimp-mcp-server. OpenTelemetry-Peer-Abhängigkeiten werden standardmäßig installiert — baue mit --build-arg OTEL_ENABLED=false, um sie wegzulassen.

Projektstruktur

Entwicklungsleitfaden

Siehe CLAUDE.md für Entwicklungsrichtlinien und Architekturregeln. Die Kurzfassung:

• Handler werfen, das Framework fängt — kein try/catch in der Tool-Logik

• Verwende ctx.log für anfragebezogenes Logging

• Registriere neue Tools und Ressourcen über die Barrels in src/mcp-server/*/definitions/index.ts

• Kapsle externe API-Aufrufe: Rohdaten validieren → in Domain-Typ normalisieren → Ausgabe-Schema zurückgeben; erfinde niemals fehlende Felder

Mitwirken

Issues und Pull Requests sind willkommen. Führe vor dem Einreichen die Checks und Tests aus:

bun run devcheck
bun run test

Lizenz

Dieses Projekt ist unter der Apache-2.0-Lizenz lizenziert. Details findest du in der Datei LICENSE.