@cyanheads/mailchimp-mcp-server

ツール

常時利用可能な18のツールに加え、条件付きの2つのツールがあります — mailchimp_assets（MAILCHIMP_ASSETS_DIRが設定されている場合）と mailchimp_local_templates（MAILCHIMP_TEMPLATES_DIRが設定されている場合）。ワークフローヘルパーは一般的なフローをエンドツーエンドでオーケストレーションし、プリミティブツールはきめ細かいCRUD操作を公開し、インストラクションツールはライブのアカウント状態と統合された手順ガイダンスを返します。

mailchimp_send_campaign

1回の呼び出しでキャンペーンの作成と送信（またはスケジュール/テスト）を行います。

• 作成 → コンテンツ → チェックリスト → 任意のテスト → 送信/スケジュールを連鎖実行

• mode: 'send' | 'schedule' の場合、キャンペーンへの変更前に再入可能な入力ラウンドを通じて人間による確認を要求

• cleanupOnError: true（デフォルト）の場合、失敗した下書きを自動削除。確認が拒否された場合はレビュー可能な下書きを残す

• html、plaintext、templateId + templateSections、ローカル Eta テンプレートのコンテンツ形式に対応

mailchimp_replicate_campaign

既存のキャンペーンを任意の上書きを指定して複製し、送信/スケジュール/テスト、または下書きのまま残します。

• 上書き：件名、送信者名、返信先、オーディエンス、セグメント、コンテンツ

• mailchimp_send_campaign と同じ再入可能な確認 + クリーンアップのセマンティクス

• 「先週のニュースレターの v2 を更新したイントロで送信する」という一般的なパターンに最適化

mailchimp_upsert_subscriber

1回の冪等な呼び出しで登録者を追加または更新します。

• 宣言的タグ同期 — 希望するアクティブセットを渡すと、ツールが追加/削除の差分を計算

• preserveTags は名前付きセグメントのメンバーシップを保護（Mailchimp は静的セグメントのメンバーシップをタグとして保存）

• status: 'pending' は Mailchimp のダブルオプトインメールをトリガー。'subscribed' は文書化された同意が必要

• 作成パスは PUT /members/{hash}、更新は PATCH を使用して、既存のマージフィールドの再検証をスキップ

mailchimp_import_subscribers

1回の呼び出しで登録者を一括追加（および必要に応じて更新）します。

• 1回の呼び出しあたり最大500行 — より大きなインポートはクライアント側で分割

• 誤った一括送信を防ぐため、ステータスはデフォルトで pending（ダブルオプトイン）

• 行ごとの成功/失敗とエラー理由を返す

mailchimp_campaign_report

キャンペーンの送信後分析の集計。

• 主要な配信メトリクス: 送信数、バウンス数、不正利用レポート

• エンゲージメント: 開封数、クリック数、配信停止数

• クリックされたリンクの上位N件、地域、最近の配信停止

• 利用可能な場合の業界ベンチマーク

• 単一のディメンションを詳細に確認するには、mailchimp_reports を operation: 'slice' とともに使用します

mailchimp_audience_overview

単一呼び出しのオーディエンス健全性ダイジェスト — 「このオーディエンスはどのような状態か?」という問いに1リクエストで答えます。

• オーディエンス情報 + ライブ統計

• 設定可能な月数の成長履歴

• 主要なメールクライアント

• 完全なマージフィールドスキーマ

• 最近のアクティビティ

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固有:

• 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は画像を 1 MB、その他のファイルを 10 MB に制限しています。サイズ超過のファイルは、アップロード前に実行可能なエラーメッセージ付きで失敗します。

• 許可される拡張子: mailchimp_files ツールの説明を参照してください。WebPとAVIFは許可リストに含まれていません — PNG/JPGに変換してください。

• パストラバーサルは拒否されます(../ および絶対パスは Forbidden をスローします)。

• mailchimp_assets ツールは Nodeのみ です。Cloudflare Workersでは登録されません。

ローカルテンプレート(オプション)

MAILCHIMP_TEMPLATES_DIR を設定すると、Eta (v4 — 高速、ESMネイティブ、パーシャル/条件分岐/ループをサポート)の上にローカルテンプレート作成ワークフローを有効にできます。これは無料プランのMailchimpアカウントでテンプレートを作成するための標準的な書き込みパスです。無料プランではアップストリームの /templates APIが読み取り専用のためです。

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 は省略可能です。--- ブロックのない本文は、メタ情報なしのテンプレートとして扱われます。すべてのメタフィールドも省略可能です。vars: リストは情報提供のみを目的としています（宣言された変数はスキーマによって強制されません）。

サイドカーフォールバック（レガシー）: v0.3.1 より前は、メタ情報は本文の隣にある別の <name>.meta.yaml ファイルに格納されていました。この形式は後方互換性のために今も動作します。.eta にフロントマターがない場合、ローダーはサイドカーの読み取りにフォールバックします。両方が存在する場合はフロントマターが優先されます。

任意のキャンペーンツールから参照:

{
  "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（Mailchimp の base/user テンプレートを ID で読み取り、出発点としてディスクに書き込む — 読み取りはできてもアップストリームへの書き込みができない無料プランで便利）を公開しています。

このリポジトリ内のサンプルテンプレート

templates/ ディレクトリには動作するサンプルが含まれています。試すには MAILCHIMP_TEMPLATES_DIR をこのディレクトリに直接指定するか、出発点として自分のディレクトリにコピーしてください:

注意事項:

• 同じコンテンツブロックでは、localTemplate は html および templateId と相互排他的です。

• 変数の検証はスキーマによって強制されません。欠落または余分な変数は、送信時に Eta のレンダリングエラーとして表面化します。

• パストラバーサルは拒否されます。

• Node.js のみ。Workers では利用できません。

サーバーの実行

ローカル開発

• ウォッチモード（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 に開発ガイドラインとアーキテクチャ上のルールが記載されています。要約は次のとおりです:

• ハンドラーがスローし、フレームワークがキャッチする — ツールロジックに try/catch は不要

• リクエストスコープのロギングには ctx.log を使用

• 新しいツールとリソースは src/mcp-server/*/definitions/index.ts のバレルを介して登録

• 外部 API 呼び出しをラップする: 生データを検証 → ドメイン型に正規化 → 出力スキーマを返す。欠落フィールドを捏造しない

コントリビューション

Issue とプルリクエストを歓迎します。提出前にチェックとテストを実行してください:

bun run devcheck
bun run test

ライセンス

このプロジェクトは Apache 2.0 License の下でライセンスされています。詳細は LICENSE ファイルを参照してください。