Meta Ads MCP

Meta-Anzeigen MCP

Ein Model Context Protocol (MCP) -Server für die Interaktion mit der Meta Ads API. Dieses Tool ermöglicht KI-Modellen den Zugriff auf, die Analyse und Verwaltung von Meta-Werbekampagnen über eine standardisierte Schnittstelle. LLMs können so Leistungsdaten abrufen, Werbekreationen visualisieren und strategische Einblicke für Facebook, Instagram und andere Meta-Plattformen liefern.

HAFTUNGSAUSSCHLUSS: Dies ist ein inoffizielles Drittanbieter-Tool und steht in keiner Verbindung zu Meta, wird von Meta unterstützt oder ist mit Meta verbunden. Dieses Projekt wird unabhängig gepflegt und nutzt die öffentlichen APIs von Meta gemäß deren Nutzungsbedingungen. Meta, Facebook, Instagram und andere Meta-Markennamen sind Marken ihrer jeweiligen Eigentümer.

Screenshot : Verwenden eines LLM zum Verstehen der Leistung Ihrer Anzeige:

Merkmale

• KI-gestützte Kampagnenanalyse : Lassen Sie Ihr bevorzugtes LLM Ihre Kampagnen analysieren und umsetzbare Erkenntnisse zur Leistung liefern
• Strategische Empfehlungen : Erhalten Sie datengestützte Vorschläge zur Optimierung der Werbeausgaben, der Zielgruppenausrichtung und der kreativen Inhalte
• Automatisierte Überwachung : Bitten Sie jedes MCP-kompatible LLM, Leistungsmetriken zu verfolgen und Sie über signifikante Änderungen zu informieren
• Budgetoptimierung : Erhalten Sie Empfehlungen zur Umverteilung des Budgets auf leistungsstärkere Anzeigengruppen
• Kreative Verbesserung : Erhalten Sie Feedback zu Anzeigentext, Bildern und Handlungsaufforderungen
• Kampagnenmanagement : Fordern Sie Änderungen an Kampagnen, Anzeigengruppen und Anzeigen an (alle Änderungen erfordern eine ausdrückliche Bestätigung)
• Plattformübergreifende Integration : Funktioniert mit Facebook, Instagram und allen Meta-Werbeplattformen
• Universelle LLM-Unterstützung : Kompatibel mit jedem MCP-Client, einschließlich Claude Desktop, Cursor, Cherry Studio und mehr
• Einfache Authentifizierung : Einfache Einrichtung mit sicherer OAuth-Authentifizierung
• Plattformübergreifende Unterstützung : Funktioniert unter Windows, macOS und Linux

Installation

Verwendung von UV (empfohlen)

Bei der Verwendung von uv ist keine spezielle Installation erforderlich. Wir können uvx verwenden, um meta-ads-mcp direkt auszuführen:

Wenn Sie das Paket installieren möchten:

Für die Entwicklung (wenn Sie das Repository geklont haben):

Verwenden von pip

Alternativ können Sie meta-ads-mcp über pip installieren:

Nach der Installation können Sie es wie folgt ausführen:

Konfiguration

Erstellen Sie eine Meta-Entwickler-App (erforderlich)

Bevor Sie den MCP-Server verwenden, müssen Sie eine Meta Developer App einrichten:

1. Gehen Sie zu Meta für Entwickler und erstellen Sie eine neue App
2. Wählen Sie den App-Typ „Consumer“
3. Fügen Sie in Ihren App-Einstellungen das Produkt „Marketing API“ hinzu
4. Konfigurieren Sie die OAuth-Umleitungs-URI Ihrer App so, dass http://localhost:8888/callback enthält.
5. Notieren Sie Ihre App-ID (Client-ID) für die Verwendung mit dem MCP

Verwendung mit Cursor oder Claude Desktop

Fügen Sie dies zu Ihrer claude_desktop_config.json hinzu, um es mit Claude zu integrieren, oder zu ~/.cursor/mcp.json um es mit Cursor zu integrieren:

Verfügbare MCP-Tools

1. mcp_meta_ads_get_ad_accounts
   • Für einen Benutzer zugängliche Werbekonten erhalten
   • Eingänge:
     • access_token (optional): Meta-API-Zugriffstoken (wenn nicht angegeben, wird das zwischengespeicherte Token verwendet)
     • user_id : Meta-Benutzer-ID oder „me“ für den aktuellen Benutzer
     • limit : Maximale Anzahl der zurückzugebenden Konten (Standard: 10)
   • Rückgabe: Liste der zugänglichen Werbekonten mit ihren Details
2. mcp_meta_ads_get_account_info
   • Erhalten Sie detaillierte Informationen zu einem bestimmten Anzeigenkonto
   • Eingänge:
     • access_token (optional): Meta-API-Zugriffstoken (wenn nicht angegeben, wird das zwischengespeicherte Token verwendet)
     • account_id : Meta Ads-Konto-ID (Format: act_XXXXXXXXX)
   • Rückgabe: Detaillierte Informationen zum angegebenen Konto
3. mcp_meta_ads_get_account_pages
   • Mit einem Meta Ads-Konto verknüpfte Seiten abrufen
   • Eingänge:
     • access_token (optional): Meta-API-Zugriffstoken (wenn nicht angegeben, wird das zwischengespeicherte Token verwendet)
     • account_id : Meta Ads-Konto-ID (Format: act_XXXXXXXXX) oder „me“ für die Seiten des aktuellen Benutzers
   • Gibt zurück: Liste der mit dem Konto verknüpften Seiten, nützlich für die Erstellung und Verwaltung von Anzeigen
4. mcp_meta_ads_get_campaigns
   • Erhalten Sie Kampagnen für ein Meta Ads-Konto mit optionaler Filterung
   • Eingänge:
     • access_token (optional): Meta-API-Zugriffstoken (wenn nicht angegeben, wird das zwischengespeicherte Token verwendet)
     • account_id : Meta Ads-Konto-ID (Format: act_XXXXXXXXX)
     • limit : Maximale Anzahl der zurückzugebenden Kampagnen (Standard: 10)
     • status_filter : Filtern nach Status (leer für alle oder „AKTIV“, „PAUSED“ usw.)
   • Rückgabe: Liste der Kampagnen, die den Kriterien entsprechen
5. mcp_meta_ads_get_campaign_details
   • Erhalten Sie detaillierte Informationen zu einer bestimmten Kampagne
   • Eingänge:
     • access_token (optional): Meta-API-Zugriffstoken (wenn nicht angegeben, wird das zwischengespeicherte Token verwendet)
     • campaign_id : Meta Ads-Kampagnen-ID
   • Retouren: Detaillierte Informationen zur angegebenen Kampagne
6. mcp_meta_ads_create_campaign
   • Erstellen Sie eine neue Kampagne in einem Meta Ads-Konto
   • Eingänge:
     • access_token (optional): Meta-API-Zugriffstoken (wenn nicht angegeben, wird das zwischengespeicherte Token verwendet)
     • account_id : Meta Ads-Konto-ID (Format: act_XXXXXXXXX)
     • name : Kampagnenname
     • objective : Kampagnenziel (BEWUSSTSEIN, VERKEHR, ENGAGEMENT usw.)
     • status : Anfänglicher Kampagnenstatus (Standard: PAUSIERT)
     • special_ad_categories : Liste spezieller Anzeigenkategorien, falls zutreffend
     • daily_budget : Tagesbudget in Kontowährung (in Cent)
     • lifetime_budget : Lebenszeitbudget in Kontowährung (in Cent)
   • Rücksendungen: Bestätigung mit neuen Kampagnendetails
7. mcp_meta_ads_get_adsets
   • Holen Sie sich Anzeigensätze für ein Meta Ads-Konto mit optionaler Filterung nach Kampagne
   • Eingänge:
     • access_token (optional): Meta-API-Zugriffstoken (wenn nicht angegeben, wird das zwischengespeicherte Token verwendet)
     • account_id : Meta Ads-Konto-ID (Format: act_XXXXXXXXX)
     • limit : Maximale Anzahl der zurückzugebenden Anzeigengruppen (Standard: 10)
     • campaign_id : Optionale Kampagnen-ID zum Filtern
   • Gibt zurück: Liste der Anzeigengruppen, die den Kriterien entsprechen
8. mcp_meta_ads_get_adset_details
   • Erhalten Sie detaillierte Informationen zu einem bestimmten Anzeigensatz
   • Eingänge:
     • access_token (optional): Meta-API-Zugriffstoken (wenn nicht angegeben, wird das zwischengespeicherte Token verwendet)
     • adset_id : Meta Ads-Anzeigengruppen-ID
   • Gibt zurück: Detaillierte Informationen zum angegebenen Anzeigensatz
9. mcp_meta_ads_create_adset
   • Erstellen Sie einen neuen Anzeigensatz in einem Meta Ads-Konto
   • Eingänge:
     • account_id : Meta Ads-Konto-ID (Format: act_XXXXXXXXX)
     • campaign_id : Meta Ads-Kampagnen-ID, zu der dieser Anzeigensatz gehört
     • name : Name der Anzeigengruppe
     • status : Anfänglicher Status der Anzeigengruppe (Standard: PAUSIERT)
     • daily_budget : Tagesbudget in Kontowährung (in Cent) als String
     • lifetime_budget : Lebenszeitbudget in Kontowährung (in Cent) als String
     • targeting : Targeting-Spezifikationen (z. B. Alter, Standort, Interessen)
     • optimization_goal : Conversion-Optimierungsziel (z. B. „LINK_CLICKS“)
     • billing_event : Wie Ihnen die Kosten berechnet werden (z. B. „IMPRESSIONS“)
     • bid_amount : Gebotsbetrag in Kontowährung (in Cent)
     • bid_strategy : Gebotsstrategie (z. B. „LOWEST_COST“)
     • start_time , end_time : Optionale Start-/Endzeiten (ISO 8601)
     • access_token (optional): Meta-API-Zugriffstoken
   • Rücksendungen: Bestätigung mit neuen Anzeigengruppendetails
10. mcp_meta_ads_get_ads

• Erhalten Sie Anzeigen für ein Meta Ads-Konto mit optionaler Filterung
• Eingänge:
  • access_token (optional): Meta-API-Zugriffstoken (wenn nicht angegeben, wird das zwischengespeicherte Token verwendet)
  • account_id : Meta Ads-Konto-ID (Format: act_XXXXXXXXX)
  • limit : Maximale Anzahl der zurückzugebenden Anzeigen (Standard: 10)
  • campaign_id : Optionale Kampagnen-ID zum Filtern
  • adset_id : Optionale Anzeigengruppen-ID zum Filtern
• Rückgabe: Liste der Anzeigen, die den Kriterien entsprechen

11. mcp_meta_ads_create_ad

• Erstellen Sie eine neue Anzeige mit einem vorhandenen Creative
• Eingänge:
  • account_id : Meta Ads-Konto-ID (Format: act_XXXXXXXXX)
  • name : Anzeigenname
  • adset_id : Anzeigengruppen-ID, in der diese Anzeige platziert wird
  • creative_id : ID eines vorhandenen Creatives, das verwendet werden soll
  • status : Anfänglicher Anzeigenstatus (Standard: PAUSIERT)
  • bid_amount : Optionaler Gebotsbetrag (in Cent)
  • tracking_specs : Optionale Tracking-Spezifikationen
  • access_token (optional): Meta-API-Zugriffstoken
• Retouren: Bestätigung mit neuen Anzeigendetails

12. mcp_meta_ads_get_ad_details

• Erhalten Sie detaillierte Informationen zu einer bestimmten Anzeige
• Eingänge:
  • access_token (optional): Meta-API-Zugriffstoken (wenn nicht angegeben, wird das zwischengespeicherte Token verwendet)
  • ad_id : Meta Ads-Anzeigen-ID
• Retouren: Detaillierte Informationen zur angegebenen Anzeige

13. mcp_meta_ads_get_ad_creatives

• Erhalten Sie kreative Details für eine bestimmte Anzeige
• Eingänge:
  • access_token (optional): Meta-API-Zugriffstoken (wenn nicht angegeben, wird das zwischengespeicherte Token verwendet)
  • ad_id : Meta Ads-Anzeigen-ID
• Rückgabe: Kreative Details, einschließlich Text, Bilder und URLs

14. mcp_meta_ads_create_ad_creative

• Erstellen Sie ein neues Werbemittel mit einem hochgeladenen Bild-Hash
• Eingänge:
  • account_id : Meta Ads-Konto-ID (Format: act_XXXXXXXXX)
  • name : Kreativer Name
  • image_hash : Hash des hochgeladenen Bildes
  • page_id : Facebook-Seiten-ID für die Anzeige
  • link_url : Ziel-URL
  • message : Anzeigenkopie/Text
  • headline : Anzeigenüberschrift
  • description : Anzeigenbeschreibung
  • call_to_action_type : CTA-Schaltflächentyp (z. B. „MEHR ERFAHREN“)
  • instagram_actor_id : Optionale Instagram-Konto-ID
  • access_token (optional): Meta-API-Zugriffstoken
• Rücksendungen: Bestätigung mit neuen Kreativdetails

15. mcp_meta_ads_upload_ad_image

• Laden Sie ein Bild zur Verwendung in Meta Ads-Creatives hoch
• Eingänge:
  • account_id : Meta Ads-Konto-ID (Format: act_XXXXXXXXX)
  • image_path : Pfad zur hochzuladenden Bilddatei
  • name : Optionaler Name für das Bild
  • access_token (optional): Meta-API-Zugriffstoken
• Gibt zurück: JSON-Antwort mit Bilddetails einschließlich Hash

16. mcp_meta_ads_get_ad_image

• Holen, herunterladen und visualisieren Sie ein Meta-Anzeigenbild in einem Schritt
• Eingänge:
  • access_token (optional): Meta-API-Zugriffstoken (wenn nicht angegeben, wird das zwischengespeicherte Token verwendet)
  • ad_id : Meta Ads-Anzeigen-ID
• Rückgabe: Das Anzeigenbild ist bereit für die direkte visuelle Analyse

17. mcp_meta_ads_update_ad

• Aktualisieren einer Anzeige mit neuen Einstellungen
• Eingänge:
  • ad_id : Meta Ads-Anzeigen-ID
  • status : Anzeigenstatus aktualisieren (AKTIV, PAUSIERT usw.)
  • bid_amount : Gebotsbetrag in Kontowährung (in Cent für USD)
  • access_token (optional): Meta-API-Zugriffstoken (wenn nicht angegeben, wird das zwischengespeicherte Token verwendet)
• Rücksendungen: Bestätigung mit aktualisierten Anzeigendetails und einem Bestätigungslink

18. mcp_meta_ads_update_adset

• Aktualisieren Sie einen Anzeigensatz mit neuen Einstellungen, einschließlich Frequenzbegrenzungen
• Eingänge:
  • adset_id : Meta Ads-Anzeigengruppen-ID
  • frequency_control_specs : Liste der Frequenzsteuerungsspezifikationen
  • bid_strategy : Gebotsstrategie (z. B. „LOWEST_COST_WITH_BID_CAP“)
  • bid_amount : Gebotsbetrag in Kontowährung (in Cent für USD)
  • status : Aktualisieren Sie den Status der Anzeigengruppe (AKTIV, PAUSIERT usw.)
  • targeting : Targeting-Spezifikationen einschließlich Targeting_Automation
  • access_token (optional): Meta-API-Zugriffstoken (wenn nicht angegeben, wird das zwischengespeicherte Token verwendet)
• Rückgabe: Bestätigung mit aktualisierten Anzeigengruppendetails und einem Bestätigungslink

19. mcp_meta_ads_get_insights

• Erhalten Sie Leistungseinblicke für eine Kampagne, einen Anzeigensatz, eine Anzeige oder ein Konto
• Eingänge:
  • access_token (optional): Meta-API-Zugriffstoken (wenn nicht angegeben, wird das zwischengespeicherte Token verwendet)
  • object_id : ID der Kampagne, des Anzeigensatzes, der Anzeige oder des Kontos
  • time_range : Zeitbereich für Einblicke (Standard: Maximum)
  • breakdown : Optionale Aufschlüsselungsdimension (z. B. Alter, Geschlecht, Land)
  • level : Aggregationsebene (Anzeige, Anzeigengruppe, Kampagne, Konto)
• Gibt zurück: Leistungsmetriken für das angegebene Objekt

20. mcp_meta_ads_debug_image_download

• Debuggen Sie Probleme beim Herunterladen von Bildern und melden Sie detaillierte Diagnosen
• Eingänge:
  • access_token (optional): Meta-API-Zugriffstoken (wenn nicht angegeben, wird das zwischengespeicherte Token verwendet)
  • url : Direkte Bild-URL zum Testen (optional)
  • ad_id : Meta Ads-Anzeigen-ID (optional, wird verwendet, wenn keine URL angegeben ist)
• Gibt zurück: Diagnoseinformationen zu Bilddownloadversuchen

21. mcp_meta_ads_get_login_link

• Erhalten Sie einen anklickbaren Login-Link für die Meta Ads-Authentifizierung
• Eingänge:
  • access_token (optional): Meta-API-Zugriffstoken (wenn nicht angegeben, wird das zwischengespeicherte Token verwendet)
• Gibt zurück: Ein anklickbarer Ressourcenlink zur Meta-Authentifizierung

22. mcp_meta-ads_create_budget_schedule

• Erstellen Sie einen Budgetplan für eine Meta-Ads-Kampagne.
• Eingänge:
  • campaign_id : Meta Ads-Kampagnen-ID.
  • budget_value : Betrag der Budgeterhöhung.
  • budget_value_type : Typ des Budgetwerts („ABSOLUT“ oder „MULTIPLIER“).
  • time_start : Unix-Zeitstempel für den Beginn der Hochlastperiode.
  • time_end : Unix-Zeitstempel für das Ende der Hochlastperiode.
  • access_token (optional): Meta-API-Zugriffstoken.
• Gibt zurück: JSON-Zeichenfolge mit der ID des erstellten Budgetplans oder eine Fehlermeldung.

Authentifizierung

Das Meta Ads MCP verwendet den OAuth 2.0-Authentifizierungsfluss von Meta, der für Desktop-Apps entwickelt wurde:

Bei der Authentifizierung wird Folgendes durchgeführt:

1. Starten Sie einen lokalen Rückrufserver auf Ihrem Computer
2. Öffnen Sie ein Browserfenster, um sich bei Meta zu authentifizieren
3. Bitten Sie Sie, die App zu autorisieren
4. Leiten Sie zurück zum lokalen Server, um das Token zu extrahieren und sicher zu speichern

Für diese Methode müssen Sie wie oben beschrieben eine Meta Developer App erstellen .

Fehlerbehebung und Protokollierung

Das Meta Ads MCP enthält ein umfassendes Protokollierungssystem zur Unterstützung der Fehlerbehebung:

Protokollspeicherort

Protokolldateien werden an einem plattformspezifischen Speicherort gespeichert:

• macOS : ~/Library/Application Support/meta-ads-mcp/meta_ads_debug.log
• Windows : %APPDATA%\meta-ads-mcp\meta_ads_debug.log
• Linux : ~/.config/meta-ads-mcp/meta_ads_debug.log

Häufige Probleme

Authentifizierungsprobleme

Wenn Fehler wie (#200) Provide valid app ID auftreten, überprüfen Sie Folgendes:

• Stellen Sie sicher, dass Sie eine Meta Developer App korrekt eingerichtet haben
• Überprüfen Sie mit einer der folgenden Methoden, ob Sie die richtige App-ID übergeben:
  • Legen Sie die Umgebungsvariable META_APP_ID fest: export META_APP_ID=your_app_id
  • Übergeben Sie es als Befehlszeilenargument: meta-ads-mcp --app-id your_app_id

API-Fehler

Wenn Sie Fehler von der Meta-API erhalten:

1. Überprüfen Sie, ob Ihrer App das Marketing-API-Produkt hinzugefügt wurde.
2. Stellen Sie sicher, dass der Benutzer über die entsprechenden Berechtigungen für die Werbekonten verfügt
3. Überprüfen Sie, ob für Ihre App Ratenbegrenzungen oder andere Einschränkungen gelten

Debugging-Befehl

Verwenden Sie bei bestimmten Problemen beim Herunterladen von Bildern das integrierte Diagnosetool:

Dadurch erhalten Sie detaillierte Informationen zum Downloadvorgang und möglichen Problemen.

Ausführen mit unterschiedlichen App-IDs

Wenn Sie für unterschiedliche Zwecke unterschiedliche Meta-App-IDs verwenden müssen:

Datenschutz und Sicherheit

Das Meta Ads MCP befolgt bewährte Sicherheitspraktiken:

1. Token werden an einem plattformspezifischen sicheren Ort zwischengespeichert:
   • Windows: %APPDATA%\meta-ads-mcp\token_cache.json
   • macOS: ~/Library/Application Support/meta-ads-mcp/token_cache.json
   • Linux: ~/.config/meta-ads-mcp/token_cache.json
2. Sie müssen Ihr Zugriffstoken nicht für jeden Befehl angeben; es wird automatisch aus dem Cache abgerufen.
3. Sie können die Umgebungsvariable META_APP_ID festlegen, anstatt sie als Argument zu übergeben:
   export META_APP_ID=your_app_id uvx meta-ads-mcp
4. Sie können ein Direktzugriffstoken mit der Umgebungsvariable META_ACCESS_TOKEN bereitstellen. Dadurch werden sowohl der lokale Token-Cache als auch die Pipeboard-Authentifizierungsmethode umgangen:
   export META_ACCESS_TOKEN=your_access_token uvx meta-ads-mcp
   Dies ist nützlich für CI/CD-Pipelines oder wenn Sie bereits über ein gültiges Zugriffstoken aus einer anderen Quelle verfügen.

Testen

CLI-Tests

Führen Sie das Testskript aus, um die Authentifizierung und die grundlegende Funktionalität zu überprüfen:

Verwenden Sie das Flag --force-login um eine neue Authentifizierung zu erzwingen, auch wenn ein zwischengespeichertes Token vorhanden ist:

LLM-Schnittstellentests

Bei Verwendung des Meta Ads MCP mit einer LLM-Schnittstelle (wie Claude):

1. Testen Sie die Authentifizierung, indem Sie das Tool mcp_meta_ads_get_login_link aufrufen
2. Überprüfen Sie den Kontozugriff, indem Sie mcp_meta_ads_get_ad_accounts aufrufen
3. Überprüfen Sie spezifische Kontodetails mit mcp_meta_ads_get_account_info

Diese Funktionen übernehmen bei Bedarf automatisch die Authentifizierung und stellen bei Bedarf einen anklickbaren Anmeldelink bereit.

Fehlerbehebung

Authentifizierungsprobleme

Wenn bei der Authentifizierung Probleme auftreten:

1. Bei Verwendung der LLM-Schnittstelle:
   • Verwenden Sie das Tool mcp_meta_ads_get_login_link , um einen neuen Authentifizierungslink zu generieren
   • Stellen Sie sicher, dass Sie auf den Link klicken und den Autorisierungsvorgang in Ihrem Browser abschließen
   • Überprüfen Sie, ob der Callback-Server ordnungsgemäß läuft (das Tool meldet dies).
2. Bei Verwendung von direktem Meta OAuth:
   • Führen Sie es mit --force-login aus, um ein neues Token zu erhalten: uvx meta-ads-mcp --login --app-id YOUR_APP_ID --force-login
   • Stellen Sie sicher, dass das Terminal über die Berechtigung zum Öffnen eines Browserfensters verfügt
3. Überspringen Sie die Authentifizierung vollständig, indem Sie direkt ein Token angeben:
   • Wenn Sie bereits über ein gültiges Zugriffstoken verfügen, können Sie den Authentifizierungsablauf umgehen:
   • export META_ACCESS_TOKEN=your_access_token
   • Dadurch werden sowohl der lokale Token-Cache als auch die Pipeboard-Authentifizierung ignoriert

API-Fehler

Wenn Sie Fehler von der Meta-API erhalten:

1. Überprüfen Sie, ob Ihrer App das Marketing-API-Produkt hinzugefügt wurde.
2. Stellen Sie sicher, dass der Benutzer über die entsprechenden Berechtigungen für die Werbekonten verfügt
3. Überprüfen Sie, ob für Ihre App Ratenbegrenzungen oder andere Einschränkungen gelten

Versionierung

Sie können die aktuelle Version des Pakets überprüfen: