KonQuest Meta Ads MCP

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

オープンコアモデル

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

パブリック版（本リポジトリ） - 57ツール、MITライセンス:

• キャンペーン、広告セット、広告のフルCRUD

• マルチアセット広告作成（動画 + 静止画、マルチディメンション）

• 画像のアップロードと取得

• キャンペーンと広告セットの複製

• インサイトおよびアカウント横断的な一括分析

• ピクセルおよびトラッキング診断（5ツール）

• カタログおよびDPAサポート（6ツール、製品セットの作成/更新を含む）

• 完全なターゲティングツールキット（6ツール）

• セットアップ準備状況チェッカー（修正手順付きの42以上のチェック）

• 検証パイプライン、命名規則の強制、書き込み後の検証

• 安全性ティア、レート制限、ロールバック参照

• 215の自動テスト

プレミアムバンドル - 41ツールを追加:

• アドバイザリー最適化エンジン（レビューキュー、学習、実験、予算ガバナー、クリエイティブローテーション）

• ボールトインテリジェンスとコピー生成（ブランドボイス、ICPターゲティング、コンセプト選択）

• ギリシャ語QA（Greeklish検出、正書法チェック）

• 自動化スイート（診断、一括操作、アカウント監査）

• ボールトブートストラップ（クライアントごとに15のテンプレートファイル）

• プレミアムテストと評価

プレミアムバンドルは別途入手可能です。パブリックツールはそれなしでも完全に動作します。

特徴

• 本番環境でテスト済み - 37以上のクライアントキャンペーンで、実際の予算とエッジケースに対応

• 単なるラッパーではない - 最適化エンジン、安全ゲート、バリデーター、ロールバックを内蔵

• ボールト統合 - クライアントのインテリジェンス（ICP、ブランドボイス、アングル）を読み取り、より良い広告を生成

• ギリシャ語QAを内蔵（あらゆる言語の検証に適応可能）

• すべての広告は「一時停止」で作成 - オペレーターの明示的な承認なしに公開されることはありません

• 自律型ではなく監視型 - すべての書き込み、有効化、予算変更をオペレーターが確認

ツール分類

アーキテクチャ

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)

ツールカテゴリ

エンジン機能

• 最適化ループ - パフォーマンスシグナルに基づく自動予算シフト

• 実験管理 - 統計的有意性を伴うA/Bテスト追跡

• 予算ガバナー - 設定可能な日次/生涯制限による過剰支出の防止

• クリエイティブローテーション - 疲労検出と自動クリエイティブ更新トリガー

• ポリシー学習 - アクションの結果を追跡し、時間の経過とともに信頼性を適応

• 命名ゲート - API書き込み前の命名規則の厳格な強制

安全機能

• レート制限 - バックオフを伴うMeta APIレート制限の遵守

• ロールバック - 実行ジャーナルによる最近の変更の取り消し

• 重複チェック - キャンペーン/広告の誤った重複作成を防止

• ファイルロック - ボールトストレージへの安全な同時アクセス

• ティアベースアクセス - アカウントごとの安全性ティア（サンドボックス、標準、本番）

バリデータスイート

• コンプライアンスバリデータ - 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 - マーケティングボールトディレクトリへのパス（デフォルトは ~/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. ボールト構造 (オプション)

クライアントインテリジェンスのためにボールト統合を使用する場合:

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 を参照してください。