@cyanheads/mailchimp-mcp-server

도구

항상 활성화된 도구 18개와 조건부 도구 2개 — 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

선택적 재정의와 함께 기존 캠페인을 복제한 다음 전송/예약/테스트하거나 초안으로 남겨 둡니다.

• 재정의: 제목, 보낸 사람 이름, 회신 주소, 잠재 고객, 세그먼트, 콘텐츠

• 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

캠페인에 대한 집계된 전송 후 분석.

• 주요 전송 지표: 전송, 반송, 스팸 신고

• 참여: 오픈, 클릭, 구독 취소

• 상위 N개 클릭 링크, 위치, 최근 구독 취소

• 가능한 경우 업계 벤치마크

• 단일 차원을 자세히 보려면 mailchimp_reports를 operation: 'slice'와 함께 사용하세요.

mailchimp_audience_overview

단일 호출 오디언스 상태 요약 — 한 번의 요청으로 "이 오디언스는 어떤 모습일까?"에 답합니다.

• 오디언스 정보 + 실시간 통계

• 구성 가능한 개월 수의 성장 이력

• 상위 이메일 클라이언트

• 전체 병합 필드 스키마

• 최근 활동

mailchimp_playbook

실시간 계정 상태와 결합된 구조화된 절차형 플레이북을 반환합니다. 조언 전용입니다. 에이전트는 이후 단계를 다른 도구로 실행합니다.

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

• 마크다운 지침 + 실시간 상태 스냅샷 반환

• 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 전용:

• API 키의 -dc 접미사에서 API 기본 URL을 자동으로 파생

• 기본적으로 안전한 전송 워크플로 — 재진입 확인, 보류 상태 가져오기, 에이전트 표면에서 영구 삭제 없음

• 워크플로 도구는 구성 가능한 동시성 제한 하에 관련 하위 요청을 병렬화

• 도메인 정규화는 희소한 업스트림 페이로드를 값을 조작하지 않고 간결하고 LLM 친화적인 출력으로 변환

시작하기

MCP 클라이언트 구성 파일에 다음을 추가하세요. Mailchimp API 키 생성 방법은 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"
      }
    }
  }
}

또는 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+).

• Mailchimp Marketing API 키 — 키의 -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/<relative-path>로 참조하면 서버가 전송 시 업로드하고 재작성합니다.

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_files 도구 표면을 통해 Mailchimp File Manager에 업로드합니다.

3. sha256 → file_id + URL을 <assetsDir>/.mailchimp-cache.json에 캐시합니다(원자적 쓰기, 강제 재업로드를 위해 삭제해도 안전).

4. 콘텐츠를 업스트림에 전달하기 전에 모든 @assets/<path>를 공개 CDN URL로 재작성합니다.

mailchimp_assets 도구는 직접 검사를 위해 list, info, sync(사전 워밍), clear-cache를 제공합니다. 대부분의 워크플로에서는 필요하지 않습니다.

주의 사항:

• Mailchimp는 이미지를 1MB, 기타 파일을 10MB로 제한합니다. 초과 크기 파일은 업로드 전에 실행 가능한 오류와 함께 실패합니다.

• 허용 확장자: mailchimp_files 도구 설명을 참조하세요. WebP와 AVIF는 허용 목록에 없습니다 — PNG/JPG로 변환하세요.

• 경로 탐색은 거부됩니다(../ 및 절대 경로는 Forbidden을 발생시킵니다).

• mailchimp_assets 도구는 Node 전용입니다. Cloudflare Workers에서는 등록되지 않습니다.

로컬 템플릿(선택 사항)

MAILCHIMP_TEMPLATES_DIR을 설정하면 Eta(v4 — 빠르고, ESM 네이티브이며, 부분 템플릿/조건문/반복문 지원) 기반의 로컬 템플릿 작성 워크플로를 사용할 수 있습니다. 업스트림 /templates API가 읽기 전용인 무료 티어 Mailchimp 계정에서 템플릿을 작성하는 표준 경로입니다.

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 frontmatter, 아래에 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는 선택 사항입니다 — --- 블록이 없는 본문은 메타가 없는 템플릿으로 처리됩니다. 모든 메타 필드도 선택 사항입니다. vars: 목록은 정보 제공용일 뿐입니다(선언된 변수는 스키마로 강제되지 않습니다).

사이드카 폴백(레거시): v0.3.1 이전에는 메타가 본문 옆의 별도 <name>.meta.yaml 파일에 있었습니다. 이 형식은 하위 호환성을 위해 여전히 작동합니다 — .eta에 frontmatter가 없으면 로더는 사이드카를 읽는 방식으로 폴백합니다. 둘 다 존재하면 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가 it = { firstName: 'Sam', brand: 'Acme' }로 welcome.eta를 렌더링합니다.

2. L1이 구성된 경우 @assets/hero.png가 Mailchimp File Manager에 업로드되고 CDN URL로 다시 작성됩니다.

3. 최종 HTML은 Mailchimp의 set-content를 통해 캠페인에 설정됩니다.

mailchimp_local_templates 도구는 list, get, render-preview(전송 없이 HTML 반환), seed-from-mailchimp(ID로 Mailchimp base/user 템플릿을 읽어 디스크에 시작점으로 기록 — 무료 플랜에서는 업스트림에 쓸 수 없고 읽기만 가능하므로 유용함)를 제공합니다.

이 저장소의 예제 템플릿

templates/ 디렉터리에는 작동하는 예제가 있습니다 — MAILCHIMP_TEMPLATES_DIR을 이 디렉터리로 직접 지정해 시도하거나, 시작점으로 자신의 디렉터리에 복사하세요:

주의 사항:

• localTemplate는 동일한 콘텐츠 블록에서 html 및 templateId와 상호 배타적입니다.

• 변수 검증은 스키마로 강제되지 않습니다 — 누락/추가 변수는 전송 시 Eta 렌더링 오류로 나타납니다.

• 경로 탐색은 거부됩니다.

• 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에 로그를 남깁니다. OpenTelemetry 피어 종속성은 기본적으로 설치됩니다 — 이를 제외하려면 --build-arg OTEL_ENABLED=false로 빌드하세요.

프로젝트 구조

개발 가이드

개발 지침과 아키텍처 규칙은 CLAUDE.md를 참조하세요. 요약은 다음과 같습니다:

• 핸들러는 throw하고 프레임워크가 catch합니다 — 도구 로직에는 try/catch가 없습니다.

• 요청 범위 로깅에는 ctx.log를 사용하세요.

• 새 도구와 리소스는 src/mcp-server/*/definitions/index.ts의 배럴을 통해 등록하세요.

• 외부 API 호출을 래핑하세요: 원시 데이터 검증 → 도메인 타입으로 정규화 → 출력 스키마 반환; 누락된 필드를 임의로 만들지 마세요.

기여

이슈와 풀 리퀘스트를 환영합니다. 제출 전에 검사와 테스트를 실행하세요:

bun run devcheck
bun run test

라이선스

이 프로젝트는 Apache 2.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 LICENSE 파일을 참조하세요.