Meta Ads CLI installieren: Schritt-für-Schritt-Anleitung

Meta Ads CLI installieren dauert weniger als zehn Minuten, wenn die Voraussetzungen stimmen. Metas offizielles Kommandozeilen-Tool gibt Entwicklern und KI-Agenten direkten Zugriff auf Kampagnen, Anzeigengruppen, Creatives und Performance-Daten, ohne den Umweg über den Ads Manager. Meta hat das Tool am 29. April 2026 veröffentlicht und richtet es laut offiziellem Blogpost ausdrücklich an Entwickler und AI Agents. Diese Anleitung führt Sie von der Python-Installation über das Token-Setup bis zum ersten funktionierenden Befehl. Die strategische Einordnung finden Sie im Überblick zur Meta Ads CLI.

Voraussetzungen: Was Sie vor der Installation brauchen

Bevor Sie die Meta Ads CLI installieren, müssen vier Bausteine stehen. Fehlt einer davon, scheitert die Einrichtung spätestens beim ersten Befehl. Die gute Nachricht: Alle Komponenten sind kostenlos verfügbar.

1. Python 3.12 oder neuer - Die CLI läuft als Python-Paket. Ältere Python-Versionen werden nicht unterstützt.
2. pip oder uv als Paketmanager - pip ist bei Python standardmäßig dabei. uv ist schneller und empfiehlt sich für Projekte mit mehreren Abhängigkeiten.
3. Meta-App mit Marketing-API-Zugang - Sie brauchen eine registrierte App im Meta for Developers Portal mit aktivierter Marketing API.
4. System User Token - Ein langlebiger Access Token mit den Berechtigungen ads_management und ads_read. Persönliche Tokens laufen zu schnell ab und eignen sich nicht für Automatisierung.

Python-Version pruefen

Öffnen Sie Ihr Terminal und prüfen Sie die installierte Python-Version:

python3 --version

Die Ausgabe muss Python 3.12.x oder höher zeigen. Falls Sie eine ältere Version sehen, laden Sie die aktuelle Version von python.org herunter oder nutzen Sie Ihren Paketmanager (brew install python auf macOS, apt install python3.12 auf Ubuntu/Debian). Auf Windows funktioniert die Installation über den offiziellen Installer von python.org am zuverlässigsten.

Meta Ads CLI installieren: pip oder uv?

Die Installation selbst besteht aus einem einzigen Befehl. Je nach Paketmanager wählen Sie eine der beiden Varianten.

Installation mit pip

pip install meta-ads-cli

Installation mit uv

uv pip install meta-ads-cli

Nach der Installation prüfen Sie, ob das Tool korrekt verfügbar ist:

meta-ads --version

Kommt eine Versionsnummer zurück, ist die Installation abgeschlossen. Falls der Befehl nicht gefunden wird, stellen Sie sicher, dass das Python-Scripts-Verzeichnis in Ihrem PATH liegt.

Beide Varianten liefern dasselbe Ergebnis. Für die reine CLI-Installation macht der Paketmanager keinen funktionalen Unterschied. Bei größeren Setups mit mehreren Python-Paketen spart uv spürbar Zeit bei der Auflösung von Abhängigkeiten.

Wie richte ich den API-Zugang und das Token ein?

Die CLI ist installiert, aber ohne gültigen Token passiert nichts. Meta Ads CLI nutzt die Marketing API im Hintergrund. Der Zugang läuft über eine Meta-App und einen System User Token. Das Token-Setup ist der Schritt, an dem die meisten Nutzer beim ersten Mal hängen bleiben.

Meta-App erstellen

1. Öffnen Sie das Meta for Developers Portal unter developers.facebook.com.
2. Erstellen Sie eine neue App vom Typ “Business”.
3. Aktivieren Sie das Produkt “Marketing API” in den App-Einstellungen.
4. Notieren Sie sich die App-ID und das App Secret aus den Grundeinstellungen.
5. Setzen Sie die App in den Live-Modus. Im Entwicklungsmodus sind API-Aufrufe auf Testkonten beschränkt.

System User Token generieren

Ein System User Token ist die richtige Wahl für die CLI. Er ist nicht an ein persönliches Facebook-Konto gebunden und hat eine konfigurierbare Laufzeit. Der häufigste Fehler bei der Einrichtung: Teams starten mit einem persönlichen Access Token statt mit einem System User Token. Persönliche Tokens sind an ein Benutzerkonto gebunden und laufen regelmäßig ab. Für automatisierte Workflows und den Einsatz mit KI-Agenten brauchen Sie einen System User im Business Manager.

1. Navigieren Sie im Meta Business Manager zu Unternehmenseinstellungen > System Users.
2. Erstellen Sie einen neuen System User oder wählen Sie einen bestehenden.
3. Weisen Sie dem System User Zugriff auf das gewünschte Werbekonto (Account) zu.
4. Generieren Sie einen Token mit den Berechtigungen ads_management und ads_read.
5. Kopieren Sie den Token sofort - er wird nur einmal angezeigt.

Umgebungsvariablen setzen

Der Token gehört nicht in den Code oder in ein Skript, sondern in eine Umgebungsvariable. So bleibt er aus der Versionsverwaltung heraus und liegt nicht im Klartext in Ihren Dateien.

export META_ADS_ACCESS_TOKEN="Ihr-Token-hier"
export META_ADS_APP_ID="Ihre-App-ID"
export META_ADS_APP_SECRET="Ihr-App-Secret"

Für dauerhaften Zugriff fügen Sie diese Zeilen in Ihre .bashrc, .zshrc oder .env-Datei ein. In produktiven Umgebungen empfiehlt sich ein Secrets Manager. Wichtig: Tokens und Secrets gehören nicht in ein Git-Repository.

Was ist der erste Testbefehl nach der Installation?

Der schnellste Weg, die Installation zu validieren, ist ein Lesebefehl auf Ihr Werbekonto. Dieser Befehl ändert nichts an Ihrem Account und zeigt nur vorhandene Kampagnen an.

meta-ads campaign list --account-id act_123456 --format table

Ersetzen Sie act_123456 durch Ihre tatsächliche Werbekonto-ID. Sie finden die ID im Meta Ads Manager unter Kontoeinstellungen. Das Präfix act_ ist Pflicht.

Wenn alles korrekt eingerichtet ist, sehen Sie eine Tabelle mit Ihren Kampagnen. Die CLI gibt standardmäßig Name, Status, Budget und Kampagnenziel aus. Drei Ausgabeformate stehen zur Verfügung:

1. table für die schnelle visuelle Übersicht im Terminal
2. json für die Weiterverarbeitung in Skripten und durch KI-Agenten
3. plain für einfache Textausgabe ohne Formatierung

Einen umfassenden Überblick über alle verfügbaren Kommandos finden Sie in unserer Referenz der Ads CLI Befehle.

Welche Fehler treten bei der Installation am häufigsten auf?

Die meisten Probleme bei der Einrichtung fallen in vier Kategorien. Die Exit-Codes der CLI helfen bei der schnellen Diagnose: 0 bedeutet Erfolg, 3 steht für Authentifizierungsfehler und 4 für API-Fehler.

Falsche Python-Version

ERROR: meta-ads-cli requires Python >=3.12

Sie nutzen Python 3.11 oder älter. Auf Systemen mit mehreren Python-Versionen hilft python3.12 -m pip install meta-ads-cli, um explizit die richtige Version anzusprechen. Prüfen Sie vorher mit python3 --version, welche Version aktiv ist.

Authentifizierung schlägt fehl (Exit-Code 3)

Error: Authentication failed. Check your access token.

Die CLI gibt bei Token-Problemen den Exit-Code 3 zurück. Häufige Ursachen sind ein abgelaufener Token, fehlende Berechtigungen (ads_management, ads_read), eine nicht gesetzte Umgebungsvariable oder ein System User ohne Zugriff auf das angegebene Werbekonto.

Prüfen Sie zuerst, ob die Umgebungsvariable korrekt gesetzt ist:

echo $META_ADS_ACCESS_TOKEN

Wenn die Ausgabe leer ist, wurde die Variable nicht gesetzt oder die Shell-Sitzung wurde zwischenzeitlich neu gestartet.

API-Fehler (Exit-Code 4)

Die CLI gibt Exit-Code 4 zurück, wenn die Marketing API einen Fehler meldet. Das passiert häufig, wenn die Werbekonto-ID falsch formatiert ist (sie muss mit act_ beginnen), die App noch im Entwicklungsmodus läuft oder Rate Limits der API erreicht sind. Bei Rate Limits hilft es, einige Minuten zu warten und den Befehl erneut auszuführen.

pip findet das Paket nicht

ERROR: No matching distribution found for meta-ads-cli

Wenn pip das Paket nicht findet, prüfen Sie Ihre pip-Version mit pip --version. Eine veraltete pip-Version kann Pakete auf dem Python Package Index nicht korrekt auflösen. Aktualisieren Sie pip mit pip install --upgrade pip und versuchen Sie die Installation erneut.

Wie geht es nach der Installation weiter?

Mit einer funktionierenden CLI-Installation stehen Ihnen mehrere Wege offen. Der naheliegendste Einstieg ist ein Analyse-Workflow: Kampagnen auflisten, Performance-Daten abrufen und die Ergebnisse in einem strukturierten Format exportieren.

Erster Analyse-Workflow

meta-ads insights get --account-id act_123456 \
  --date-range last_7d \
  --metrics impressions,clicks,spend,ctr \
  --format json

Dieser Befehl liefert die wichtigsten Performance-Kennzahlen der letzten sieben Tage als JSON. Das ist exakt das Format, mit dem KI-Agenten wie Claude Code oder Codex weiterarbeiten können. Ein Agent kann diese Daten interpretieren, Auffälligkeiten erkennen und konkrete Optimierungsvorschläge formulieren.

Einstieg in agentische Workflows

Die eigentliche Stärke der Meta Ads CLI entfaltet sich in Kombination mit KI-Agenten. Claude Code kann die CLI als Tool nutzen, Performance-Daten interpretieren und strukturierte Empfehlungen erstellen. Kampagnen analysieren, Creatives vergleichen, Budget-Empfehlungen ableiten - das funktioniert über die CLI deutlich systematischer als über manuelle Klickarbeit im Ads Manager. Wie Sie solche Workflows aufsetzen, beschreibt unser Guide zur Ads CLI mit KI-Agenten.

Wer die strategische Einordnung sucht, warum dieses Tool für Performance Marketing, Agenturen und Unternehmen relevant ist, findet sie im Überblick zu Meta Ads CLI.

Meta Ads CLI installieren: Alle Schritte auf einen Blick

Die gesamte Einrichtung der Meta Ads CLI dauert unter zwanzig Minuten, wenn Sie bereits ein Meta Business Manager Konto und ein aktives Werbekonto haben. Der häufigste Stolperstein ist das Token-Setup. Nehmen Sie sich für diesen Schritt die meiste Zeit und achten Sie darauf, einen System User Token statt eines persönlichen Tokens zu verwenden.

Sie möchten KI-gestützte Werbe-Workflows mit der Meta Ads CLI in Ihrem Unternehmen aufbauen? Sprechen Sie uns an - wir beraten Sie unverbindlich.