@cyanheads/mailchimp-mcp-server

Инструменты

Восемнадцать постоянно доступных инструментов плюс два условных — mailchimp_assets (когда задан MAILCHIMP_ASSETS_DIR) и mailchimp_local_templates (когда задан MAILCHIMP_TEMPLATES_DIR). Помощники рабочих процессов оркестрируют типовые сценарии от начала до конца, базовые инструменты предоставляют детализированные CRUD-операции, а инструмент-инструкция возвращает процедурные рекомендации в сочетании с актуальным состоянием аккаунта.

mailchimp_send_campaign

Создание и отправка (или планирование/тест) кампании одним вызовом.

• Выстраивает цепочку: создание → контент → чек-лист → необязательный тест → отправка/планирование

• Запрашивает подтверждение человека через повторный запрос ввода перед любой мутацией кампании, когда mode: 'send' | 'schedule'

• Автоматически удаляет неудачные черновики при cleanupOnError: true (по умолчанию); при отклонении подтверждения остаётся черновик для проверки

• Поддерживает формы контента html, plaintext, templateId + templateSections и локальные шаблоны Eta

mailchimp_replicate_campaign

Дублирование существующей кампании с необязательными переопределениями, затем отправка/планирование/тест или оставить черновиком.

• Переопределения: тема, имя отправителя, reply-to, аудитория, сегмент, контент

• Та же семантика повторного подтверждения и очистки, что и у mailchimp_send_campaign

• Заточено под частый сценарий «отправить v2 прошлого выпуска рассылки с обновлённым вступлением»

mailchimp_upsert_subscriber

Добавление или обновление подписчика одним идемпотентным вызовом.

• Декларативная синхронизация тегов — передайте желаемый активный набор, и инструмент вычислит дельту добавления/удаления

• preserveTags защищает членство в именованных сегментах (Mailchimp хранит членство в статических сегментах как теги)

• status: 'pending' запускает письмо двойного подтверждения Mailchimp; 'subscribed' требует документально подтверждённого согласия

• PUT /members/{hash} для пути создания, PATCH для обновления, чтобы пропустить повторную валидацию существующих полей слияния

mailchimp_import_subscribers

Пакетное добавление (и при необходимости обновление) подписчиков одним вызовом.

• Не более 500 строк за вызов — разбивайте более крупные импорты на стороне клиента

• Статус по умолчанию — pending (двойное подтверждение), чтобы предотвратить случайные массовые отправки

• Возвращает по каждой строке успех/неудачу с причинами ошибок

mailchimp_campaign_report

Агрегированная аналитика по кампании после отправки.

• Ключевые метрики рассылки: отправлено, отказы, жалобы на спам

• Вовлеченность: открытия, клики, отписки

• Top-N кликнутых ссылок, география, недавние отписки

• Отраслевые бенчмарки при наличии

• Используйте mailchimp_reports с operation: 'slice' для детального просмотра одного измерения

mailchimp_audience_overview

Компактная сводка здоровья аудитории за один вызов — отвечает на вопрос «как выглядит эта аудитория?» одним запросом.

• Информация об аудитории + живые статистики

• Настраиваемое количество месяцев истории роста

• Основные почтовые клиенты

• Полная схема merge-полей

• Недавняя активность

mailchimp_playbook

Возвращает структурированный процедурный плейбук, объединенный с текущим состоянием аккаунта. Только рекомендации — агент выполняет последующие шаги с помощью других инструментов.

• Темы: send, post-send-review, deliverability, list-hygiene, onboarding, subscriber-triage, design-campaign

• Возвращает markdown-инструкции + снимок текущего состояния

• nextToolSuggestions предзаполняет аргументы для следующего вероятного вызова инструмента

Related MCP server: Mailchimp MCP Server

Ресурсы и промпты

Все данные ресурсов также доступны через инструменты. Большие коллекции (audiences, campaigns) не представлены как ресурсы — используйте операцию list соответствующего инструмента. Дизайн-референс для промпта: docs/email-design-playbook.md.

Возможности

Построен на @cyanheads/mcp-ts-core:

• Декларативные определения инструментов, ресурсов и промптов — один файл на примитив, фреймворк берет на себя регистрацию и валидацию

• Единая обработка ошибок — обработчики выбрасывают исключения, фреймворк перехватывает, классифицирует и форматирует

• Подключаемая аутентификация: none, jwt, oauth

• Структурированное логирование с опциональным трассировкой OpenTelemetry

• Транспорты STDIO и Streamable HTTP

Специфично для Mailchimp:

• Автоматически выводит базовый URL API из суффикса -dc в API-ключе

• Безопасные по умолчанию рабочие процессы отправки — повторное подтверждение, импорты со статусом pending, отсутствие необратимых удалений из поверхности агента

• Инструменты рабочих процессов параллелизуют связанные подзапросы с настраиваемым лимитом конкурентности

• Нормализация доменов преобразует разреженные ответы вышестоящего API в компактный, удобный для LLM вывод без выдумывания значений

Начало работы

Добавьте следующее в файл конфигурации вашего MCP-клиента. См. docs/api-key.md о том, как сгенерировать API-ключ 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"
      }
    }
  }
}

Или через npx (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"
      }
    }
  }
}

Или через 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"
      ]
    }
  }
}

Для Streamable HTTP задайте транспорт и запустите сервер:

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

Предварительные требования

• Bun v1.4.0 или выше (или Node.js v24+).

• API-ключ Mailchimp Marketing — суффикс -dc в ключе (например, -us22) определяет ваш дата-центр и разбирается при запуске.

Установка

1. Клонируйте репозиторий:

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

2. Перейдите в каталог:

cd mailchimp-mcp-server

3. Установите зависимости:

bun install

4. Настройте окружение:

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

Конфигурация

Полный список опциональных переопределений см. в .env.example.

Локальные ресурсы (опционально)

Задайте MAILCHIMP_ASSETS_DIR, чтобы включить рабочий процесс с локальными изображениями поверх Mailchimp File Manager. Поместите файлы изображений в каталог, ссылайтесь на них в HTML как @assets/<относительный-путь>, и сервер загрузит и перепишет их при отправке.

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

Затем в кампании:

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

Когда mailchimp_send_campaign (или mailchimp_campaigns set-content / mailchimp_replicate_campaign contentOverride) видит эти ссылки, он:

1. Хеширует каждый указанный файл (SHA-256).

2. Загружает промахи кэша в Mailchimp File Manager через поверхность инструмента mailchimp_files.

3. Кэширует sha256 → file_id + URL в <assetsDir>/.mailchimp-cache.json (атомарные записи; файл можно безопасно удалить для принудительной повторной загрузки).

4. Переписывает каждый @assets/<path> на публичный CDN-URL перед передачей контента вышестоящему API.

Инструмент mailchimp_assets предоставляет list, info, sync (предварительный прогрев) и clear-cache для прямого просмотра — большинству рабочих процессов он не нужен.

Ограничения:

• Mailchimp ограничивает изображения 1 МБ, а другие файлы — 10 МБ. Файлы большего размера отклоняются до загрузки с понятной ошибкой.

• Допустимые расширения: см. описание инструмента mailchimp_files. WebP и AVIF НЕ входят в список разрешенных — конвертируйте в PNG/JPG.

• Обход пути запрещен (../ и абсолютные пути вызывают ошибку Forbidden).

• Инструмент mailchimp_assets доступен только в Node; на Cloudflare Workers он не регистрируется.

Локальные шаблоны (опционально)

Задайте MAILCHIMP_TEMPLATES_DIR, чтобы включить рабочий процесс создания локальных шаблонов поверх Eta (v4 — быстрый, нативный ESM, поддерживает партиалы/условия/циклы). Это канонический путь записи шаблонов для аккаунтов Mailchimp на бесплатном тарифе, где вышестоящий API /templates доступен только для чтения.

export MAILCHIMP_TEMPLATES_DIR=/Users/me/email-templates

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

Шаблон (welcome.eta) — YAML-фронтматтер сверху, тело Eta ниже:

---
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 is optional — a body with no --- block is treated as a meta-less template. All meta fields are optional too. The vars: list is informational only (declared variables aren't schema-enforced).

Резервный механизм sidecar (legacy): до v0.3.1 метаданные хранились в отдельном файле <name>.meta.yaml рядом с телом шаблона. Эта форма по-прежнему работает для обратной совместимости — если у .eta нет frontmatter, загрузчик откатывается к чтению sidecar-файла. Если существуют оба, приоритет у frontmatter.

Ссылка из любого инструмента кампании:

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

Конвейер рендеринга:

1. Eta рендерит welcome.eta с параметром it = { firstName: 'Sam', brand: 'Acme' }.

2. Если L1 настроен, @assets/hero.png загружается в Mailchimp File Manager и заменяется на CDN-URL.

3. Итоговый HTML задаётся для кампании через set-content Mailchimp.

Инструмент mailchimp_local_templates предоставляет list, get, render-preview (возвращает HTML без отправки) и seed-from-mailchimp (читает шаблон Mailchimp base/user по ID и записывает его на диск как отправную точку — полезно на бесплатном тарифе, где можно читать, но нельзя записывать в апстрим).

Примеры шаблонов в этом репозитории

Директория templates/ содержит рабочие примеры — направьте MAILCHIMP_TEMPLATES_DIR на неё, чтобы попробовать их, или скопируйте их в свою директорию как отправную точку:

Предостережения:

• localTemplate взаимоисключающ с html и templateId в одном блоке контента.

• Валидация переменных не выполняется схемой — недостающие/лишние переменные проявляются как ошибки рендеринга Eta при отправке.

• Обход пути (path traversal) отклоняется.

• Только Node; недоступно на Workers.

Запуск сервера

Локальная разработка

• Режим watch (транспорт через MCP_TRANSPORT_TYPE):

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

• Сборка и запуск:

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

• Запуск проверок и тестов:

  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

Dockerfile по умолчанию использует HTTP-транспорт, режим сессии без состояния и записывает логи в /var/log/mailchimp-mcp-server. Peer-зависимости OpenTelemetry устанавливаются по умолчанию — соберите образ с --build-arg OTEL_ENABLED=false, чтобы исключить их.

Структура проекта

Руководство по разработке

Смотрите CLAUDE.md — там правила разработки и архитектурные принципы. Если коротко:

• Обработчики выбрасывают исключения, фреймворк перехватывает их — никаких try/catch в логике инструментов.

• Используйте ctx.log для логирования в рамках запроса.

• Регистрируйте новые инструменты и ресурсы через barrel-файлы в src/mcp-server/*/definitions/index.ts.

• Оборачивайте внешние API-вызовы: валидируйте сырые данные → нормализуйте до доменного типа → возвращайте выходную схему; никогда не выдумывайте отсутствующие поля.

Участие в разработке

Приветствуются issues и pull requests. Перед отправкой запускайте проверки и тесты:

bun run devcheck
bun run test

Лицензия

Этот проект распространяется по лицензии Apache 2.0. Подробности — в файле LICENSE.