sfmc-mcp-server

SFMC MCP Server

Claude（または任意の MCP クライアント）を Salesforce Marketing Cloud に接続します。Data Extension を探索し、レコードを照会し、Automation Studio のクエリを実行前に検証できます。

---

問題点

SFMC を運用している方なら、よくある状況をご存じでしょう。Query Activity を作成して保存し、自動化を実行すると、30 分後に EmailAddress ではなく EmailAdress と入力したことに気づきます。または、Automation Studio の方言ではサポートされていない ORDER BY を使っていたり、出力列が出力先の DE に存在しなかったりします。

SFMC のフィードバックループは数十分単位です。この MCP サーバーを使えば、数秒に短縮できます。

できること

ツール	解決すること
validate_sql	Query Activity を実行する前に検証します。SFMC の制限付き方言のルールと、DE および列が実際に存在するかどうかを確認します
list_data_extensions	メタデータ、名前によるフィルター、ページネーション、完全なスキーマを含む DE の一覧を取得します
query_data_extension	フィルター、並べ替え、ページネーションを指定してレコードを照会します

validate_sql の動作例

Você: valide essa query pra mim

SELECT c.SubscriberKey, c.EmailAdress, c.LastPurchaseDate
FROM Customers_Master c
ORDER BY c.CreatedDate DESC

❌ INVÁLIDA — 3 erro(s) bloqueante(s).

1. ORDER BY não é suportado em Query Activities do SFMC. [linha ~3]
   → Se precisar de ranking, use ROW_NUMBER() OVER (ORDER BY ...) em subquery.

2. A coluna "EmailAdress" não existe na DE "Customers_Master".
   → Você quis dizer "EmailAddress"?

3. A coluna "LastPurchaseDate" não existe na DE "Customers_Master".
   → Campos disponíveis: SubscriberKey, EmailAddress, FirstName, Status, CreatedDate

検出できる項目：

方言のルール — ORDER BY、CTE（WITH）、MERGE、DML／DDL、変数（DECLARE @）、一時テーブル（#temp）、カーソル、ストアドプロシージャ、FULL OUTER JOIN、括弧の不一致、リスクのある SELECT *、サーバーのタイムゾーンでの GETDATE()。

実際のスキーマとの照合 — 存在しない DE、存在しない列（編集距離に基づく修正候補を提示）、宣言されていないエイリアス、出力先の DE と互換性のない出力列、SELECT に含まれていない出力先の PK（SFMC で最もコストの高いサイレントエラー）。

---

インストール

npx sfmc-mcp-server

または、ローカルにインストールします。

npm install -g sfmc-mcp-server

設定

1. SFMC で Installed Package を作成する

Setup → Apps → Installed Packages → New → Add Component → API Integration (Server-to-Server)

最低限必要な権限（読み取り専用）：

• Data Extensions：Read
• Automations：Read

Client ID、Client Secret、およびサブドメイン（.auth.marketingcloudapis.com より前の部分）を控えてください。

2. Claude Desktop を設定する

~/Library/Application Support/Claude/claude_desktop_config.json（macOS） %APPDATA%\Claude\claude_desktop_config.json（Windows）

{
  "mcpServers": {
    "sfmc": {
      "command": "npx",
      "args": ["-y", "sfmc-mcp-server"],
      "env": {
        "SFMC_SUBDOMAIN": "mcXXXXXXXXXXXXXXXXXXXXXX",
        "SFMC_CLIENT_ID": "seu_client_id",
        "SFMC_CLIENT_SECRET": "seu_client_secret",
        "SFMC_MODE": "read"
      }
    }
  }
}

Claude Desktop を再起動すれば完了です。

複数の Business Unit

BU ごとにエントリーを作成し、それぞれの SFMC_ACCOUNT_ID（MID）を指定します。

{
  "mcpServers": {
    "sfmc-varejo": {
      "command": "npx",
      "args": ["-y", "sfmc-mcp-server"],
      "env": { "SFMC_ACCOUNT_ID": "1234567", "...": "..." }
    },
    "sfmc-b2b": {
      "command": "npx",
      "args": ["-y", "sfmc-mcp-server"],
      "env": { "SFMC_ACCOUNT_ID": "7654321", "...": "..." }
    }
  }
}

---

使用例

• 「このクエリを出力先の DE Active_Buyers と照合して検証して」 → 30 分を無駄にする前にエラーを指摘します
• 「名前に 'master' が含まれる DE をフィールドとともに一覧表示して」 → Contact Builder を開かずに完全なスキーマを確認できます
• 「Customers_Master には有効なレコードがいくつある？」 → フィルターを指定して直接照会します
• 「この DE に主キーはある？ NOT NULL のフィールドはどれ？」 → 数秒でスキーマを監査できます

---

セキュリティ

• デフォルトでは読み取り専用です。 SFMC_MODE=read がデフォルトです。書き込みツール（ロードマップ）は、SFMC_MODE=write の場合にのみ登録されます。
• 認証情報は環境変数を通じてのみ渡します。 コミットされることも、ディスクに保存されることもありません。
• 監査ログ。 すべてのツール呼び出しはタイムスタンプと引数とともに stderr に出力されます。ポリシーに応じてファイルまたはコレクターにリダイレクトしてください。
• データを保持しません。 サーバーは SFMC のデータを永続化しません。

---

アーキテクチャ

src/
├── index.ts               # Entry point — registra tools, transporte stdio
├── auth.ts                # OAuth client_credentials, cache de token (~20 min)
├── sfmcClient.ts          # REST client com retry exponencial (429/5xx)
└── tools/
    ├── validateSql.ts     # Regras do dialeto + validação contra schema real
    ├── listDataExtensions.ts
    └── queryDataExtension.ts

実装の詳細：

• トークンをキャッシュし、有効期限の 60 秒前を余裕として扱います（SFMC のトークンは約 18〜20 分で期限切れになります）
• 429／5xx に対して指数バックオフで再試行します。SFMC は負荷が高いと簡単にスロットリングします
• 認証は遅延実行されます。認証情報がなくてもサーバーは起動し、最初のツール呼び出し時に検証します
• クエリではページネーションを必須とし、モデルのコンテキストを超えないよう最大 50 行に制限します

---

ロードマップ

• get_automation_status — ステータスと実行履歴
• list_journeys — アクティブなジャーニー、バージョン、メトリクス
• get_send_stats — 開封、クリック、バウンス
• upsert_rows — チェックポイント／再開パターンによる書き込み（write モード）
• SOAP 経由で Parent BU の Shared Data Extensions をサポート

---

既知の制限事項

• validate_sql は、Automation Studio の既知の制約とテーブル／列の存在を検証します。論理的な正しさやパフォーマンスは保証しません。
• 共有 DE（ENT.）はスキーマに対して検証されません。Parent BU にあり、現在の BU の REST の対象外です。
• 修飾されていない列（alias. プレフィックスのない列）は、複数の JOIN を含むクエリでは検証されません。これを解決するには、完全な SQL パーサーが必要です。
• /data/v1/customobjects エンドポイントは比較的新しいものです。古いリリースのインスタンスでは、SOAP へのフォールバックが必要になる場合があります。

---

貢献

PR を歓迎します。最も効果の大きい領域は、ロードマップにあるツールと SFMC 方言の新しい検証ルールです。Automation Studio に拒否される構文に時間を取られたことがある場合は、その事例を添えて issue を作成してください。

ライセンス

MIT