KonQuest Meta Ads MCP

Überwachtes Meta Ads-Betriebssystem für Claude Code. Die Premium-Version finden Sie hier: https://farasokster.gumroad.com/l/konquest-meta-ads-mcp-premium

Open-Core-Modell

KonQuest Meta Ads MCP verwendet ein Open-Core-Modell:

Öffentlich (dieses Repo) – 57 Tools, MIT-Lizenz:

• Vollständiges CRUD für Kampagnen, Anzeigengruppen und Anzeigen

• Multi-Asset-Anzeigenerstellung (Video + statisches Bild, mehrdimensional)

• Bild-Upload und -Abruf

• Duplizierung von Kampagnen und Anzeigengruppen

• Insights und kontoübergreifende Bulk-Analysen

• Pixel- und Tracking-Diagnose (5 Tools)

• Katalog- und DPA-Unterstützung (6 Tools, einschließlich Erstellung/Aktualisierung von Produktsets)

• Vollständiges Targeting-Toolkit (6 Tools)

• Setup-Bereitschaftsprüfung (42+ Prüfungen mit Korrekturanweisungen)

• Validierungs-Pipeline, Namenskonventionen-Durchsetzung, Post-Write-Verifizierung

• Sicherheitsstufen, Ratenbegrenzung, Rollback-Referenzen

• 215 automatisierte Tests

Premium-Paket – fügt 41 Tools hinzu:

• Beratende Optimierungs-Engine (Review-Warteschlangen, Lernen, Experimente, Budget-Regler, Creative-Rotation)

• Vault-Intelligenz und Copy-Generierung (Markenstimme, ICP-Targeting, Konzeptauswahl)

• Griechische Sprach-QA (Erkennung von Greeklish, Rechtschreibprüfungen)

• Automatisierungssuite (Diagnose, Bulk-Operationen, Konto-Audit)

• Vault-Bootstrap (15 Vorlagendateien pro Kunde)

• Premium-Tests und -Evaluierungen

Das Premium-Paket ist separat erhältlich. Öffentliche Tools funktionieren auch ohne dieses vollständig.

Was macht dies anders?

• Produktionserprobt bei über 37 Kundenkampagnen mit echten Budgets und realen Edge-Cases

• Kein Wrapper – enthält Optimierungs-Engine, Sicherheits-Gates, Validatoren und Rollback

• Vault-integriert – liest Kundeninformationen (ICPs, Markenstimme, Blickwinkel), um bessere Anzeigen zu generieren

• Griechische Sprach-QA integriert (anpassbar an jede Sprachvalidierung)

• Alle Anzeigen werden PAUSIERT erstellt – nichts geht ohne ausdrückliche Genehmigung des Operators live

• Überwacht, nicht autonom – der Operator bestätigt jeden Schreibvorgang, jede Aktivierung, jede Budgetänderung

Tool-Klassifizierung

Architektur

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)

Tool-Kategorien

Engine-Funktionen

• Optimierungsschleifen – automatisierte Budgetverschiebung basierend auf Leistungssignalen

• Experiment-Management – A/B-Test-Tracking mit statistischer Signifikanz

• Budget-Regler – verhindern Mehrausgaben mit konfigurierbaren Tages-/Gesamtlimits

• Creative-Rotation – Ermüdungserkennung und automatische Auslöser für Creative-Refresh

• Richtlinienlernen – verfolgt Aktionsergebnisse und passt das Vertrauen im Laufe der Zeit an

• Namens-Gate – harte Durchsetzung von Namenskonventionen vor jedem API-Schreibvorgang

Sicherheitsfunktionen

• Ratenbegrenzung – respektiert Meta-API-Ratenbegrenzungen mit Backoff

• Rollback – macht kürzliche Änderungen mit Ausführungsprotokoll rückgängig

• Duplikatprüfung – verhindert versehentliche doppelte Kampagnen/Anzeigen

• Dateisperren – sicherer gleichzeitiger Zugriff auf den Vault-Speicher

• Stufenbasierter Zugriff – Sicherheitsstufen pro Konto (Sandbox, Standard, Produktion)

Validator-Suite

• Compliance-Validator – Vorabprüfung der Meta-Anzeigenrichtlinien

• Creative-Spec-Validator – Validierung von Bild-/Videoabmessungen und -formaten

• Tracking-Validator – Pixel- und Ereignisverifizierung vor dem Start

• Struktur-Validator – Konsistenzprüfungen der Kampagnenstruktur

• Operational-Validator – Plausibilitätsprüfungen für Budget, Zeitplan und Targeting

Nicht ausgelieferter Code

Code, der im Repository vorhanden ist, aber NICHT Teil der aktiven Tool-Oberfläche ist:

• reporting/templates.py, reporting/formatter.py – werden zur Laufzeit nicht importiert, keine aktive Berichterstellung

• evals/ – interne Evaluierungs-Stubs, nicht für den Operator sichtbar

• Interne Helfer (keine MCP-Tools): identity.py (IG-Auflösung), api.py (HTTP-Client), auth.py (Token-Verifizierung), utils.py (Format-Helfer), safety/ (Ratenbegrenzer, Rollback, Dedup), validators/ (Pre-Write-Validierungs-Pipeline)

Setup

1. Installieren

cd meta-ads-mcp
uv sync

2. Umgebungsvariablen

Kopieren Sie .env.example nach .env und füllen Sie Ihre Werte aus:

cp .env.example .env

Erforderlich:

• META_ACCESS_TOKEN – Meta Marketing API-Zugriffstoken (Systembenutzer-Token empfohlen)

Optional:

• META_APP_SECRET – für appsecret_proof (empfohlen für Produktion)

• META_APP_ID – Meta App-ID

• VAULT_PATH – Pfad zu Ihrem Marketing-Vault-Verzeichnis (Standard: ~/marketing-vault)

3. MCP-Konfiguration

Fügen Sie dies zu Ihrer Claude Code MCP-Konfiguration (.mcp.json) hinzu:

{
  "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-Struktur (Optional)

Bei Verwendung der Vault-Integration für Kundeninformationen:

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

Testen

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

Lizenz

MIT – siehe LICENSE.