KonQuest Meta Ads MCP

KonQuest Meta Ads MCP

Claude Code 向けの監督付き Meta Ads オペレーティングシステムです。 プレミアム版はこちらで入手できます：https://farasokster.gumroad.com/l/konquest-meta-ads-mcp-premium

オープンコアモデル

KonQuest Meta Ads MCP はオープンコアモデルを採用しています：

公開版（このリポジトリ）— 57 個のツール、MIT ライセンス：

• キャンペーン、広告セット、広告の完全な CRUD
• 複数アセットの広告作成（動画＋静止画像、複数の寸法）
• 画像のアップロードと取得
• キャンペーンと広告セットの複製
• インサイトと複数アカウントの一括分析
• ピクセルとトラッキングの診断（5 個のツール）
• カタログと DPA のサポート（商品セットの作成・更新を含む 6 個のツール）
• 完全なターゲティングツールキット（6 個のツール）
• セットアップ準備状況チェッカー（修正手順付きの 42 項目以上のチェック）
• 検証パイプライン、命名規則の適用、書き込み後の検証
• 安全性ティア、レート制限、ロールバック参照
• 215 個の自動テスト

プレミアムバンドル — 41 個のツールを追加：

• アドバイザリー最適化エンジン（レビューキュー、学習、実験、予算管理、クリエイティブのローテーション）
• Vault インテリジェンスとコピー生成（ブランドボイス、ICP ターゲティング、コンセプト選定）
• ギリシャ語の QA（ギリシャ語のラテン文字表記の検出、正書法チェック）
• 自動化スイート（診断、一括操作、アカウント監査）
• Vault のブートストラップ（クライアントごとに 15 個のテンプレートファイル）
• プレミアムテストと評価

プレミアムバンドルは別途ご利用いただけます。公開版のツールは、プレミアムバンドルがなくても完全に動作します。

この製品の特長

• 実際の予算と現実のエッジケースを含む、37 件以上のクライアントキャンペーンで本番環境のテスト済みです
• 単なるラッパーではありません — 最適化エンジン、安全性ゲート、バリデーター、ロールバック機能を備えています
• Vault と統合 — クライアントのインテリジェンス（ICP、ブランドボイス、訴求軸）を読み取り、より効果的な広告を生成します
• ギリシャ語の QA を内蔵しています（任意の言語の検証に適応可能です）
• すべての広告は一時停止状態で作成されます — オペレーターの明示的な承認なしに公開されることはありません
• 自律型ではなく、監督付きです — オペレーターはすべての書き込み、すべての有効化、すべての予算変更を確認します

ツールの分類

分類	数	説明
本番環境で安全	38	読み取り専用のデータアクセスです。API への書き込みやローカル状態の変更はありません。
監督下でのみ実行	29	実行前にオペレーターの承認が必要な書き込み・削除操作です。
アドバイザリー専用	31	推奨事項、計画、コピー、診断を生成します。Meta API への書き込みはありません。ローカルファイルに書き込む場合があります。
登録済み合計：98

アーキテクチャ

meta_ads_mcp/
  core/          # 66 tools - API read/write operations
  engine/        # 32 tools - optimization, review, learning, experiments
  validators/    # Quality gates (compliance, creative specs, tracking, structure)
  safety/        # Rate limiting, rollback, duplicate checking, file locks, tier access
  ingestion/     # Internal: video manifest management
  reporting/     # Internal: not currently active (see Non-Shipped Code)

ツールカテゴリ

カテゴリ	ツール数	説明
アカウント管理	6	トークンの健全性、広告アカウント、ページ、IG ID、検索
キャンペーン	4	キャンペーンの作成、読み取り、更新
広告セット	4	ターゲティングを含む広告セットの作成、読み取り、更新
広告	4	広告の作成、読み取り、更新
クリエイティブ	3	広告クリエイティブの作成、読み取り
インサイトと分析	1	アーキタイプを考慮した正規化によるパフォーマンスデータ
ピクセルとトラッキング	5	ピクセルの健全性、イベント診断、テストイベント、CAPI
カタログとDPA	6	商品カタログ、フィード、商品セット、検証
オーディエンス	1	カスタムオーディエンスの一覧表示
ターゲティング	3	興味・関心、行動、地域の検索
動画管理	3	アップロード（シンプルおよび再開可能）と処理状況
広告ビルダー	1	IG ゲートの適用を伴う複数アセットの広告作成
コピーエンジン	2	Vault を利用した広告コピーの生成と検証
命名規則	1	すべてのオブジェクトに命名スキーマを適用
自動化と診断	6	ギリシャ語 QA、完全診断、一括操作、アカウント監査
Vault とインテリジェンス	2	クライアント Vault の読み取り、コンセプトの選択
最適化エンジン	4	最適化サイクル、ローンチ計画、実行パック
変更コリドー	2	検証を伴う予算・ターゲティングの変更
有効化とロールバック	4	事前チェックを伴うステータス変更と取り消し
レビューキュー	7	オペレーターのレビューキュー、結果スナップショット、ダイジェスト
学習レイヤー	5	ポリシーメモリ、結果評価、学習サイクル
実験	7	A/B テスト、予算ガバナー、クリエイティブローテーション、スケーリング
コピー生成	2	自動コピーの連鎖、Vault に基づくギリシャ語コピー

エンジンの機能

• 最適化ループ - パフォーマンスシグナルに基づく予算の自動振り分け
• 実験管理 - 統計的有意性を伴う A/B テストの追跡
• 予算ガバナー - 設定可能な日次・期間全体の上限により、過剰な支出を防止
• クリエイティブローテーション - 疲弊の検出とクリエイティブの自動更新トリガー
• ポリシー学習 - アクションの結果を追跡し、時間の経過とともに信頼度を適応
• 命名ゲート - API への書き込み前に命名規則を厳格に適用

安全機能

• レート制限 - バックオフを伴って Meta API のレート制限を順守
• ロールバック - 実行ジャーナルを使用して最近の変更を取り消し
• 重複チェック - キャンペーンや広告の誤った重複を防止
• ファイルロック - Vault ストレージへの安全な同時アクセス
• ティアベースのアクセス - アカウントごとの安全ティア（サンドボックス、標準、本番環境）

バリデーター群

• コンプライアンスバリデーター - Meta 広告ポリシーの事前チェック
• クリエイティブ仕様バリデーター - 画像・動画の寸法と形式を検証
• トラッキングバリデーター - ローンチ前にピクセルとイベントを検証
• 構造バリデーター - キャンペーン構造の整合性チェック
• 運用バリデーター - 予算、スケジュール、ターゲティングの妥当性チェック

配布対象外のコード

リポジトリに存在するものの、有効なツール範囲には含まれないコードです。

• reporting/templates.py, reporting/formatter.py - 実行時にはインポートされず、有効なレポート生成機能はありません
• evals/ - 内部評価用のスタブであり、オペレーター向けではありません
• 内部ヘルパー（MCP ツールではありません）：identity.py（IG の解決）、api.py（HTTP クライアント）、auth.py（トークン検証）、utils.py（形式ヘルパー）、safety/（レート制限、ロールバック、重複排除）、validators/（書き込み前の検証パイプライン）

セットアップ

1. インストール

cd meta-ads-mcp
uv sync

2. 環境変数

.env.example を .env にコピーし、値を入力します。

cp .env.example .env

必須：

• META_ACCESS_TOKEN - Meta Marketing API アクセストークン（システムユーザートークンを推奨）

任意：

• META_APP_SECRET - appsecret_proof 用（本番環境では推奨）
• META_APP_ID - Meta アプリ ID
• VAULT_PATH - マーケティング Vault ディレクトリへのパス（デフォルトは ~/marketing-vault）

3. MCP の設定

Claude Code の MCP 設定（.mcp.json）に追加します。

{
  "mcpServers": {
    "meta-ads": {
      "command": "uv",
      "args": ["--directory", "/path/to/meta-ads-mcp", "run", "python", "-m", "meta_ads_mcp"],
      "env": {
        "META_ACCESS_TOKEN": "your_token_here",
        "VAULT_PATH": "/path/to/your/marketing-vault"
      }
    }
  }
}

4. Vault 構造（任意）

クライアントインテリジェンスに vault 統合を使用する場合：

your-vault/
  01_CLIENTS/{client-slug}/
    00-profile.md        # Account IDs, pixel, page, IG
    02-icp-personas.md   # Target audience profiles
    04-brand-voice.md    # Tone, language, style rules
    05-messaging-house.md # Angles, value props
    08-objections.md     # Objections + bias deployment
    matrix.md            # Decision Matrix
  02_COMPETITORS/{slug}/
    landscape.md         # Competitive landscape

テスト

uv run --extra dev python -m pytest tests/ -v
# Public package: 215 passed | Full (with premium): 246 passed

ライセンス

MIT - LICENSE を参照してください。