Ads Uploader

Dokumentation

MCP, CLI und API

MCP-Konfiguration

MCP (Model Context Protocol) ist ein Standard, über den KI-Apps externe Tools nutzen. Der Ads Uploader MCP-Server gibt deinem KI-Agenten denselben Funktionsumfang, den auch das CLI nutzt: Werbekonten, Kampagnen, Ad Sets und Anzeigen durchsuchen, Medien hochladen, Presets speichern, mit gespeicherten Builds arbeiten, die Vorschau eines Builds ansehen und Anzeigen erstellen. Wenn du die Web-App oder das CLI kennst, folgen die MCP-Tools genau demselben Workflow.

Der MCP-Zugriff ist für zahlende Pläne gedacht und in der Testphase nicht verfügbar. Er nutzt dasselbe Konto und dieselbe Meta-Verbindung wie Web-App und CLI und ist immer dann ausgeschaltet, wenn der CLI-Zugriff für ein Konto ausgeschaltet ist.

CLI oder MCP?

Beide laufen auf derselben Infrastruktur. Du wählst also einen Workflow, keine Funktionen. Das CLI passt besser, wenn du deinen kompletten Ablauf über einen KI-Agenten laufen lassen willst: Bulk-Uploads von der Festplatte, wiederholte Launches und komplette Builds, die im Terminal zusammengestellt werden.

Das MCP ist besser für gezielte Aufgaben, bei denen die Web-App eingebunden bleibt. Zum Beispiel:

  • Lade alle deine Medien im Web-Uploader hoch und prüfe sie, dann übergib den Build für einen einzelnen Schritt an den Agenten
  • Lass den Agenten die Ad-Set-Konfiguration einrichten
  • Lass den Agenten deine Anzeigentexte schreiben oder umschreiben
  • Ordne Anzeigentexte aus einer Tabelle den Dateinamen deiner Uploads zu

Gespeicherte Builds verbinden beides. Web-Uploader, CLI und MCP nutzen alle dieselben Build-Referenzen, sodass ein Build hin und her wandern kann, ohne dass ihn jemand neu eintippen muss. Siehe Gespeicherte Builds.

Chat-App verbinden (Claude, ChatGPT, Cursor)

Nutze den gehosteten Server, wenn du aus einer Chat-App heraus arbeitest und dich über deinen Browser anmelden willst. Füge diese URL in deiner App als benutzerdefinierten Connector hinzu:

https://adsuploader.com/api/mcp

In Claude gehst du zum Beispiel zu Settings > Connectors > Add custom connector. ChatGPT und Cursor unterstützen ebenfalls benutzerdefinierte MCP-Connectors. Schließ nach dem Hinzufügen die Anmeldung bei Ads Uploader und den Zustimmungsbildschirm in deinem Browser ab. Es gibt kein Token, das du kopieren oder einfügen musst. Um zu prüfen, ob alles funktioniert, bitte deinen Agenten, deine Werbekonten aufzulisten.

Mit einem API-Schlüssel verbinden (für deine eigenen Agenten und Skripte)

Die OAuth-Anmeldung ist der normale Weg, um eine KI-App wie Claude oder ChatGPT zu verbinden. Nutze einen API-Schlüssel für langfristige Verbindungen deiner eigenen Agenten und Skripte, wenn die Anmeldung im Browser unpraktisch ist. Erstelle ihn unter Account > MCP, CLI & API. Jeder Schlüssel ist für eine Person bestimmt. Unter API-Schlüssel findest du die Anleitung zum Erstellen, Verwenden und Widerrufen.

Sende Authorization: Bearer adk_... an https://adsuploader.com/api/mcp. Bei einem MCP-Client, der eigene Header unterstützt, kann die Konfiguration so aussehen:

{
  "mcpServers": {
    "ads-uploader": {
      "url": "https://adsuploader.com/api/mcp",
      "headers": { "Authorization": "Bearer adk_..." }
    }
  }
}

Coding-Agent verbinden (Claude Code, Claude Desktop, Cursor)

Coding-Agenten können denselben gehosteten Server nutzen. Führe in Claude Code Folgendes aus:

claude mcp add --transport http ads-uploader https://adsuploader.com/api/mcp

In anderen Agenten fügst du https://adsuploader.com/api/mcp als Remote-MCP-Server hinzu und schließt die Anmeldung im Browser ab, wenn du dazu aufgefordert wirst. Unterstützt dein Agent nur lokale (stdio-)Server, verbindest du ihn mit npx mcp-remote https://adsuploader.com/api/mcp mit dem gehosteten Server.

Server auf deinem eigenen Rechner ausführen

Du kannst den MCP-Server auch lokal ausführen. Das ist praktisch, wenn der Agent Dateien direkt von deiner Festplatte hochladen soll. Dafür brauchst du Node.js 18 oder neuer:

npm install -g @adsuploader/cli @adsuploader/mcp
ads login

Füge dann den Befehl ads-mcp zu den MCP-Einstellungen deines Agenten hinzu:

{
  "mcpServers": {
    "ads-uploader": {
      "command": "ads-mcp"
    }
  }
}

Der lokale Server nutzt den Login, den ads login gespeichert hat. Er öffnet selbst keinen Browser. Führe ads login also erneut aus, wenn dieser Login abläuft (nach 30 Tagen).

Was dein Agent tun kann

Der Server gibt deinem Agenten Tools für den kompletten Build-Workflow. Du beschreibst in normaler Sprache, was du willst, und der Agent ruft die Tools für dich auf.

BereichWas der Agent tun kann
IdentitätBestätigen, als welcher Ads Uploader-Nutzer er angemeldet ist, bevor er etwas ändert
WerbekontenDeine Meta-Werbekonten auflisten und bei jedem Aufruf die richtige accountId übergeben
DurchsuchenKampagnen, Ad Sets, Anzeigen und Pages auflisten; die kompletten Creative-Einstellungen einer Anzeige lesen
TargetingCity-Keys, Postleitzahlen und IDs für detailliertes Targeting mit ads_search_targeting nachschlagen, damit er sie nie raten muss
PresetsGespeicherte API- und Text-Presets auflisten, ein einzelnes Preset mit ads_get_preset lesen und eine bestehende Anzeige als Preset speichern
BuildsGespeicherte Builds auflisten, lesen, speichern, aktualisieren und löschen oder einen Build mit ads_fork_build in einen neuen Entwurf kopieren, sodass das Original unverändert bleibt. Jeder Build kommt mit einem Link, der ihn im Web-Uploader öffnet.
MedienBilder und Videos in dein Werbekonto hochladen und die letzten Upload-Batches auflisten
VorschauGenau zeigen, was erstellt würde, bevor irgendetwas angelegt wird
ErstellenAnzeigen aus einem Preset, einer kopierten Anzeige, einem gespeicherten Build oder einer vollständigen Spec erstellen und den Job dann verfolgen oder abbrechen
Duplizieren per Post-IDEine Post-ID-Duplizierung mit ads_duplicate_by_post_preview als Vorschau ansehen, sie mit ads_duplicate_by_post starten und mit ads_get_duplication verfolgen

Immer zuerst die Vorschau. Auf dem gehosteten Server beobachtet ads_create den Job etwa 60 Sekunden lang. Läuft der Job dann noch, gibt das Tool die Job-Referenz zurück, und dein Agent prüft den Job mit ads_get_job weiter. Der Job selbst läuft auf dem Server und hängt nicht davon ab, dass die Verbindung offen bleibt. Auf dem lokalen Server kann ads_create bis zu 30 Minuten lang beobachten.

Mit gespeicherten Builds arbeiten

Builds werden automatisch gespeichert, während du im Web-Uploader arbeitest. Jeder hat eine dauerhafte Referenz (build_...), die unten im Konfigurationsschritt und im Fenster Saved Builds angezeigt wird. Gib diese Referenz deinem Agenten, dann kann er genau die Konfiguration lesen, die du siehst, sie ändern und in denselben Build zurückspeichern.

Ist der Build im Uploader geöffnet, holt sich der Uploader die gespeicherte Änderung und übernimmt sie für dich, sofern du keine ungespeicherten Änderungen hast. Du kannst auch auf den Aktualisieren-Button neben der Build-Referenz klicken, um sofort zu prüfen. Hast du ungespeicherte Änderungen, wenn eine externe Änderung eintrifft, fragt der Uploader, ob er die externen Änderungen laden oder deine behalten soll, damit keine Version verloren geht. Ist der Tab geschlossen, frag den Agenten nach dem Build-Link.

Die Texteditoren pro Anzeige und pro Ad Set im Web-Uploader haben Buttons für Claude und ChatGPT, die einen Chat öffnen, in dem deine Build-Referenz schon eingetragen ist. Einen Textdurchgang übergibst du also mit einem Klick. Es funktioniert auch andersherum: Bitte den Agenten, seine Arbeit als Build zu speichern, und öffne dann den Link, um alles im Browser zu prüfen, bevor irgendwelche Anzeigen erstellt werden.

Medien hochladen

Wie Dateien in dein Werbekonto kommen, hängt davon ab, wo der Server läuft:

  • Gehosteter Server (Chat-Apps und Coding-Agenten mit der gehosteten URL): Gib dem Agenten öffentliche HTTPS-Download-Links, einen öffentlichen Google Drive-Dateilink oder einen öffentlichen Drive-Ordnerlink. Ads Uploader lädt und verarbeitet die Dateien im Hintergrund, die Dateidaten laufen also nie durch den Chat.
  • Lokaler Server (ads-mcp): Der Agent kann Dateien auch direkt von deiner Festplatte hochladen. Für Ordner auf deinem Rechner kannst du außerdem das CLI mit ads upload nutzen.

Nachdem ein Link- oder Drive-Upload gestartet ist, prüft der Agent ihn mit ads_get_upload. Wenn er fertig ist, enthält das Ergebnis die Batch-Zusammenfassung, die für Vorschauen und die Anzeigenerstellung genutzt wird. Um einen ungewollten Import zu stoppen, ruft der Agent ads_cancel_job auf; bereits fertige Dateien bleiben nutzbar, und das Ergebnis zeigt, wie viele abgeschlossen wurden, fehlgeschlagen sind oder übersprungen wurden. Bilder mit dem Namen *_thumbnail werden ihrem passenden Video als eigenes Thumbnail angehängt, statt als separate Medien gezählt zu werden. Die Medienanzahl eines Ordners kann deshalb niedriger sein als seine Dateianzahl. Blockiert Google einen Ordner-Import eine Zeit lang, zeigt das Ergebnis, was abgeschlossen wurde, fehlgeschlagen ist und übersprungen wurde, damit der Agent dir sagen kann, dass du es später noch einmal versuchen sollst.

Drive-Links müssen als Anyone with the link (Viewer) freigegeben sein. Private Drive-Dateien sind eine Funktion des Web-Uploaders.

Kleine Bilder kannst du auch inline senden (insgesamt bis zu 10 MB pro Aufruf). Ein Coding-Agent, der Dateidaten selbst senden kann, kann den älteren direkten Upload-Weg anfordern, der in den Speicher von Ads Uploader hochlädt. Nur dieser Weg braucht ausgehenden Zugriff auf unseren Upload-Host. Läuft dein Agent in einer Netzwerk-Sandbox, erlaube *.adsuploader.com in der Netzwerk- oder Sandbox-Allowlist deines Agenten. Die Upload-Antwort nennt den genauen Host in allowlistHost; falls er einmal abweicht, verlass dich auf die Antwort.

Limits

  • 50 Dateien pro Upload-Aufruf. Teile größere Uploads auf mehrere Aufrufe auf.
  • Rate Limits. Aufrufe sind pro Nutzer und pro Art von Aufruf über eine gleitende Minute limitiert (zum Beispiel 120 MCP-Tool-Aufrufe pro Minute und 20 pro Minute für jede Art von Listen- oder Vorschau-Aufruf). Bei normaler Nutzung bleibst du deutlich darunter. Erreicht dein Agent ein Limit, bekommt er einen "rate limit"-Fehler und sollte warten, bevor er es erneut versucht.
  • Ein Job zur Anzeigenerstellung gleichzeitig pro Nutzer, genau wie beim CLI.

Anmeldung und Zugriff

Der gehostete Server meldet dich über OAuth an, den üblichen Ablauf "anmelden und zustimmen". Das ausgestellte Access-Token ist eine Stunde gültig. Unterstützt deine App Refresh-Tokens, bekommt sie außerdem ein Refresh-Token, das 30 Tage gültig ist, und erneuert damit das Access-Token im Hintergrund. So musst du dich nicht in jeder Sitzung neu anmelden. Andernfalls fordert dich die App auf, dich erneut anzumelden, wenn das Token abläuft.

Der Zugriff hängt an deinem Konto: Er ist nur für zahlende Pläne verfügbar, und wenn du den CLI-Zugriff für ein Konto ausschaltest, wird auch dessen MCP-Zugriff sofort entfernt.

Partnership Ads

Die MCP-Tools ads_preview und ads_create akzeptieren dieselben Partnership-Specs wie das CLI:

  • Mit deinen eigenen Medien: Füge einer normalen Medien-Spec profile.partnership.enabled: true mit den IDs deines Partners hinzu. Du kannst pro Anzeige oder pro Ad Set einen anderen Partner festlegen.
  • Aus bestehenden Instagram-Beiträgen: Importiere einen autorisierten Beitrag mit mediaItems[].kind: "partnershipPost".

Die Vorschau zeigt für jede Anzeige Partner, Genehmigung und Header-Modus, gruppiert nach Ad Set. Die vollständigen Spec-Strukturen und Limits findest du unter Partnership Ads mit eigenen Medien und Spec für Partnerschaften mit bestehenden Instagram-Beiträgen.

Product Showcase

Product Showcase zeigt Produkte aus einem Katalog unter einer einzelnen Bild- oder Videoanzeige. Vollständige Kataloganzeigen (dynamisch/DPA) werden noch nicht unterstützt.

IDs müssen Zeichenfolgen aus Ziffern sein. Empfehlungen erfordern Sales-Kampagnen (OUTCOME_SALES); manuelle Katalog-/Set-Auswahl ist auch bei anderen Zielen möglich. Karussell-, flexible, Multi-Media-, bestehende Beitrags- und Partnership-Anzeigen können Product Showcase nicht aktivieren.

Kataloge und Sets suchen, dann eine Empfehlung abrufen:

  • ads_list_catalogs({ accountId })
  • ads_list_product_sets({ accountId, catalogId, productSetId? })
  • ads_get_product_showcase_recommendation({ accountId, adUrl, pageId?, pixelId? })

Create und Preview akzeptieren productShowcase: { enabled?, catalogId?, productSetId?, useRecommendation? }; enabled ist standardmäßig true. Ohne das Feld wird die Quellanzeige übernommen. RECOMMENDED verwendet Metas Standard (choiceSource: "DEFAULT"); MUST_PICK erfordert eine Kandidaten-ID als productSetId ("MANUAL"). Bei MANUAL sind Katalog und Set erforderlich. Abweichende geprüfte IDs verwenden "MANUAL".

CLI-Flags für Create und Preview: --product-showcase <on|off|recommended>, --catalog <id>, --product-set <id>. Nur IDs bedeuten on; recommended setzt useRecommendation: true. Off setzt { enabled: false }, darf keine IDs enthalten und behält das Set der Quellanzeige bei.

Preview liefert productShowcase mit enabled, Katalog-/Set-IDs, optionalem Set-Namen, choiceSource und source (recommendation, manual, source_ad), sonst null. Empfehlungen sind schreibgeschützt. Test Mode benötigt bei Aktivierung IDs, ruft keine Katalog-API auf und weist auf die fehlende Prüfung hin. Gespeicherte UI-Auswahlen werden übernommen; Standards werden vor dem Start erneut geprüft.

←
Previous
CLI-Referenz komplett
Next
Ads Insights (Beta)
→