Apple Ads MCP

Ein lokaler Model Context Protocol-Server für die Apple Ads Platform API v1. Er bietet Codex, Claude und anderen MCP-Clients typisierte Werkzeuge für App-Store-Werberecherche, Berichte, Audits und rezeptgesteuerte Kampagnenverwaltung.

Apple Ads MCP ist unabhängige Open-Source-Software. Sie ist nicht mit Apple Inc. verbunden, von Apple Inc. unterstützt oder gesponsert. Apple Ads und App Store sind Marken von Apple Inc.

Warum Apple Ads MCP

• Agentenorientierte Werkzeuge: Eigene Apps entdecken, Keywords recherchieren, Berichte einsehen, Kampagnen prüfen und eng begrenzte Änderungen vorbereiten.

• Lokale Anmeldedaten: Der private Schlüssel bleibt auf Ihrem Rechner; OAuth-Tokens und Betriebsbelege bleiben im Arbeitsspeicher des Prozesses.

• Standardmäßig schreibgeschützt: Recherche und Berichte funktionieren ohne Aktivierung von Mutationen.

• Explizite Kontorouting: Jedes kontobezogene Werkzeug erfordert ein Profil und adAccountId.

• Sichere Mutationen: Jeder Schreibvorgang erfordert eine Vorschau, einen einmaligen Beleg mit zehn Minuten Gültigkeit und eine erneute Prüfung des aktuellen Zustands.

• Begrenzte Ausgabe: Strukturierte MCP-Inhalte, begrenzte Arrays, Paginierung, Ratenlimit-Metadaten und strukturierte Apple-Fehler.

• Tragbare Laufzeit: Ein Go-Binary für macOS, Linux und Windows sowie ein OCI-Image.

Related MCP server: OpenAI Ads MCP

Veröffentlichungsstatus

v0.1.0 ist die erste öffentliche Veröffentlichung. Die vollständige lokale Testsuite, der Race-Detektor, die statische Analyse, der Schwachstellenscan, der Geheimnisscan, die Verteilungsvalidierung und echte MCP-stdio-Tests bestehen.

Eine private Live-Abnahme mit einem betreibergesteuerten Apple-Ads-Konto bestätigte:

• OAuth, Kontodiscovery, Organisations- und App-Suche;

• Storefront-Verfügbarkeit, Keyword-Vorschläge, Beliebtheitseinblicke und begrenzte Berichte;

• Vorschau → Beleg → Anwenden → direkte API-Rücklesung;

• Erstellung von pausierten Kampagnen, Anzeigengruppen, Targeting-Keywords und negativen Keywords;

• Drift-Ablehnung, einmalige Belege, Wiederherstellung des Schreibschutzes und null Werbeausgaben.

In diesem Repository werden keine Anmeldedaten, Kontoexporte, private Kampagnendaten oder Live-Belege gespeichert.

Fähigkeiten

Lese-Werkzeuge

Rezeptgesteuerte Schreib-Werkzeuge

• Erstellen und Aktualisieren von Kampagnen, Anzeigengruppen, Targeting-Keywords und negativen Keywords.

• Verwenden Sie supply-spezifische Vorschau-Grundlagen für Anzeigen und App-Store-Creatives; die Unterstützung hängt weiterhin von der Apple-Platzierung und der Produktseiten-Kombination ab.

• Vorschau von Kampagnen-Pause/Fortsetzen, Anzeigengruppen-Geboten und CPA-Obergrenzen.

• Wenden Sie genau eine Vorschau über operations_apply an.

• Untersuchen oder verifizieren Sie einen mehrdeutigen Vorgang über operations_inspect und operations_verify.

Es gibt kein generisches Rohanfrage-Werkzeug. Apple Maps, die veraltete Campaign Management API v5, automatische Budgeterhöhungen, destruktives Löschen und Empfehlungs-Anwenden/Verwerfen-Vorgänge sind absichtlich ausgeschlossen.

Sicherheitsmodell

Eine Mutation ist nur möglich, wenn alle folgenden Bedingungen erfüllt sind:

1. Der Apple-Benutzer hat eine anerkannte API-Schreibrolle für das explizite Werbekonto.

2. Der Server startet mit --allow-writes.

3. Das ausgewählte Profil hat allowWrites: true.

4. Ein spezialisiertes *_preview-Werkzeug gibt einen Beleg zurück.

5. operations_apply erhält denselben nicht abgelaufenen Beleg.

6. Die aktuelle Apple-Ressource entspricht weiterhin dem Zustand, der während der Vorschau gelesen wurde.

Belege laufen nach zehn Minuten ab und sind einmalig. Mutationen werden nach einem mehrdeutigen Transportfehler nie erneut versucht. Der Server gibt committed_unverified zurück und erfordert eine direkte Zustandsprüfung vor jedem Folge-Schreibvorgang.

Für normale Recherche und Berichte führen Sie den Server ohne --allow-writes aus und halten Sie jedes Profil auf allowWrites: false.

Installation

GitHub Releases

Laden Sie das Archiv für Ihre Plattform von GitHub Releases herunter. Jede Veröffentlichung enthält SHA-256-Prüfsummen und SPDX-SBOMs.

Beispiel für Apple Silicon:

curl -LO https://github.com/zelentsov-dev/apple-ads-mcp/releases/download/v0.1.0/apple-ads-mcp_0.1.0_darwin_arm64.tar.gz
curl -LO https://github.com/zelentsov-dev/apple-ads-mcp/releases/download/v0.1.0/checksums.txt
shasum -a 256 -c checksums.txt --ignore-missing
tar -xzf apple-ads-mcp_0.1.0_darwin_arm64.tar.gz
sudo install -m 0755 apple-ads-mcp /usr/local/bin/apple-ads-mcp

Homebrew-Formel

Die Veröffentlichung veröffentlicht eine prüfsummen-pinnende Formel als Asset:

curl -LO https://github.com/zelentsov-dev/apple-ads-mcp/releases/download/v0.1.0/apple-ads-mcp.rb
brew install --formula ./apple-ads-mcp.rb

OCI-Image

docker pull ghcr.io/zelentsov-dev/apple-ads-mcp:0.1.0

Das Image führt standardmäßig serve --stdio aus. Mounten Sie accounts.json und den referenzierten privaten Schlüssel schreibgeschützt. Wenn der Schlüssel nur für den Besitzer lesbar ist, führen Sie den Container mit der entsprechenden Host-UID/GID aus.

Aus dem Quellcode bauen

git clone https://github.com/zelentsov-dev/apple-ads-mcp.git
cd apple-ads-mcp
go build -trimpath -o ./bin/apple-ads-mcp ./cmd/apple-ads-mcp

Go 1.26.6 oder neuer ist erforderlich.

Apple Ads API Einrichtung

Der Apple Ads API-Zugriff ist getrennt vom App Store Connect-Zugriff. Ein Apple Ads Account Admin muss einen API-Benutzer mit einer geeigneten Rolle hinzufügen. Bevorzugen Sie API Account Read Only, bis Sie Kampagnenänderungen benötigen.

Generieren Sie lokal ein ES256-Schlüsselpaar:

umask 077
openssl ecparam -name prime256v1 -genkey -noout -out apple-ads-private-key.pem
openssl ec -in apple-ads-private-key.pem -pubout -out apple-ads-public-key.pem
chmod 600 apple-ads-private-key.pem

Laden Sie nur den öffentlichen Schlüssel in Apple Ads hoch. Bewahren Sie den privaten Schlüssel außerhalb des Repositorys auf und fügen Sie ihn niemals in eine Agenten-Konversation, ein Issue oder ein Protokoll ein.

Nachdem Apple den öffentlichen Schlüssel registriert hat, notieren Sie die nicht geheime Client-ID, Team-ID und Schlüssel-ID, die in der Apple Ads-Benutzeroberfläche angezeigt werden.

Konfigurieren

Erstellen Sie ein Profil interaktiv:

apple-ads-mcp config init

Der Standardkonfigurationspfad ist:

~/.config/apple-ads-mcp/accounts.json

Entsprechendes JSON:

{
  "profiles": [
    {
      "name": "production-read-only",
      "clientId": "SEARCHADS.example-client-id",
      "teamId": "SEARCHADS.example-team-id",
      "keyId": "EXAMPLEKEY",
      "privateKeyPath": "/absolute/path/to/apple-ads-private-key.pem",
      "defaultAdAccountId": "123456789",
      "allowWrites": false
    }
  ]
}

Auf POSIX-Systemen müssen beide Dateien nur für den Besitzer lesbar sein:

chmod 600 ~/.config/apple-ads-mcp/accounts.json /absolute/path/to/apple-ads-private-key.pem

Die Konfiguration speichert nur Profilmetadaten und den Pfad zum privaten Schlüssel. Sie bettet den privaten Schlüssel niemals ein.

Validieren Sie die Authentifizierung und entdecken Sie zugängliche Konten:

apple-ads-mcp auth doctor --profile production-read-only
apple-ads-mcp accounts discover --profile production-read-only

Konfigurationspriorität:

1. --config

2. APPLE_ADS_MCP_CONFIG

3. ~/.config/apple-ads-mcp/accounts.json

4. Einzelprofil-APPLE_ADS_*-Umgebungsvariablen

Unterstützte Umgebungsvariablen sind APPLE_ADS_PROFILE, APPLE_ADS_CLIENT_ID, APPLE_ADS_TEAM_ID, APPLE_ADS_KEY_ID, APPLE_ADS_PRIVATE_KEY_PATH, APPLE_ADS_AD_ACCOUNT_ID und APPLE_ADS_ALLOW_WRITES.

MCP-Client verbinden

Starten Sie den Server über stdio:

apple-ads-mcp serve --stdio

Generische MCP-Konfiguration für Codex, Claude Desktop oder einen anderen stdio-Client:

{
  "mcpServers": {
    "apple-ads": {
      "command": "apple-ads-mcp",
      "args": ["serve", "--stdio"]
    }
  }
}

Claude Code:

claude mcp add apple-ads -- apple-ads-mcp serve --stdio

Das Release-Archiv enthält auch die Codex-Plugin-Metadaten und die apple-ads-operator-Fähigkeit. Die Fähigkeit leitet Onboarding, Recherche, Kampagnen-Workflows und Mutationssicherheit, ohne Anmeldedaten in Prompts zu platzieren.

Schreibvorgänge für eine Sitzung aktivieren

Halten Sie allowWrites: false im persistenten Profil, wann immer möglich. Für eine ausdrücklich autorisierte Wartungssitzung aktivieren Sie beide Gates vorübergehend:

APPLE_ADS_PROFILE=production-read-only \
APPLE_ADS_ALLOW_WRITES=true \
apple-ads-mcp serve --stdio --allow-writes

Die Apple-ACL, das explizite profile, die explizite adAccountId, Vorschau, Belegbindung, Ablauf und Driftprüfungen gelten weiterhin. Das Starten des Servers mit Schreib-Gates ändert selbst nichts.

Bekanntes Plattformverhalten

• Apple Ads hat keine öffentliche Sandbox. Automatisierte Live-CI ist opt-in und streng schreibgeschützt.

• Verfügbarkeit, Vorschläge, Beliebtheit, Empfehlungen und Berichte variieren je nach Konto, App, Storefront und Kampagnenverlauf.

• Kalte Konten können keine Ziel-CPA- oder Budgetempfehlungen zurückgeben.

• Apple kann endpunktspezifische Validierungs- oder Serverfehler zurückgeben. Der MCP bewahrt begrenzte sichere Details für 4xx-Antworten und hält wiederholbare Serverfehler redigiert.

• Während der Live-Abnahme lehnte Apple ein separates Ad-Objekt für die APPSTORE_SEARCH_RESULTS-Supply-Quelle ab. Search Results verwendete die veröffentlichte Standard-Produktseite der App.

• Kampagnennamen werden von Apple validiert; einige von der Weboberfläche akzeptierte Satzzeichen können von der API abgelehnt werden.

• Leistungsberichte bleiben leer, bis Lieferdaten vorhanden sind. Die Zuordnung von einer Installation zu einem Abonnement oder einer Testversion gehört zu Ihrem Attribution-Stack, nicht zu dieser API.

• Die vollständige Abdeckung des Upstream-MCP-Konformitätsläufers bleibt ausstehend, da der aktuelle Läufer Server-URLs akzeptiert, aber keinen stdio-Kindprozess starten kann. Dieses Repository testet eine echte stdio-Sitzung über das offizielle Go-SDK.

Entwicklung

gofmt -w cmd internal
go test ./...
go test -race ./...
go vet ./...
go run golang.org/x/vuln/cmd/govulncheck@v1.7.0 ./...
go run github.com/zricethezav/gitleaks/v8@v8.29.1 dir --no-banner --redact .
go run github.com/goreleaser/goreleaser/v2@v2.17.1 check
go run github.com/rhysd/actionlint/cmd/actionlint@v1.7.12
npx --yes markdownlint-cli2@0.23.2 '**/*.md'
python3 scripts/validate_distribution.py

Live-Tests erfordern explizite lokale Anmeldedaten und führen niemals automatisch Mutationen aus. Siehe CONTRIBUTING.md, SECURITY.md, die Roadmap und die maschinenlesbare Operationsmatrix.

Release-Artefakte

Jede getaggte Veröffentlichung veröffentlicht:

• macOS-, Linux- und Windows-Archive für AMD64 und ARM64, wo unterstützt;

• checksums.txt mit SHA-256-Digests;

• SPDX-Software-Stücklisten, generiert mit Syft;

• eine prüfsummen-pinnende Homebrew-Formel;

• Multi-Architektur-OCI-Images für Linux AMD64 und ARM64;

• MCP-Registry-Paketmetadaten.

Lizenz

MIT