aapl-ads-mcp

Ein MCP-Server, der Claude (und jeden MCP-kompatiblen Client) mit der Apple Search Ads API v5 verbindet.

Was ist das?

MCP (Model Context Protocol) ist ein offener Standard, der es KI-Assistenten ermöglicht, externe Tools aufzurufen. Dieser Server implementiert den MCP-stdio-Transport und stellt 9 schreibgeschützte Tools bereit, die Ihr Apple Search Ads-Konto abfragen – Kampagnen, Anzeigengruppen, Keywords und Leistungsberichte.

Sie installieren es einmal, verknüpfen es mit Claude Desktop und stellen dann Fragen in natürlicher Sprache: „Welche Keywords haben letzten Monat die meisten Installationen generiert?“ oder „Zeige mir Kampagnen mit null Impressionen in dieser Woche.“

Related MCP server: tiktok-ads-mcp

Warum?

Die offiziellen ASA-Dashboards sind gut für Menschen, aber nicht für Ad-hoc-Analysen oder automatisierte Berichte geeignet. Bestehende MCP-Alternativen sind entweder SaaS (Sie geben Ihre Schlüssel weiter) oder werden nicht mehr gepflegt. Dies ist eine selbst gehostete Open-Source-Option, die Sie kontrollieren.

Funktionen

• list_orgs — Authentifizierung überprüfen, zugängliche Organisationen auflisten

• list_campaigns — Kampagnen auflisten, optional nach Status filtern

• list_ad_groups — Anzeigengruppen für eine bestimmte Kampagne

• list_keywords — Targeting-Keywords mit Gebotsbeträgen und Match-Typ

• get_campaign_report — Impressionen, Taps, Installationen, Ausgaben, CPI, TTR nach Kampagne

• get_ad_group_report — dieselben Metriken, aufgeschlüsselt nach Anzeigengruppe

• get_keyword_report — Leistung pro Keyword mit wöchentlicher/täglicher/monatlicher Granularität

• get_search_terms_report — die tatsächlichen Suchanfragen, die Ihre Anzeigen ausgelöst haben (am nützlichsten für die Entdeckung)

Alle Tools verwenden standardmäßig die letzten 30 Tage. Berichte unterstützen die Granularität HOURLY, DAILY, WEEKLY und MONTHLY.

Einschränkungen

• Designbedingt schreibgeschützt. Keine Schreibvorgänge (Erstellen, Aktualisieren, Pausieren) in dieser Version.

• Erfordert Zugriff auf die Apple Search Ads Campaign Management API. Sie müssen einen API-Benutzer in Ihrem ASA-Konto erstellen und ein ES256-Schlüsselpaar generieren.

• Aggregierte Installationsmetriken funktionieren ohne App-seitige Integration. tapInstalls, viewInstalls und verwandte Felder in ASA-Berichten werden direkt von Apple Search Ads ausgefüllt und erfordern kein SDK in Ihrer App. AdServices / AdAttributionKit wird nur benötigt, wenn Sie Installationen innerhalb Ihrer App bestimmten Kampagnen zuordnen möchten (z. B. für die Personalisierung des Onboardings).

• Einzelne Organisation. Die Organisations-ID ist in der Konfiguration festgelegt. Ein Wechsel zwischen mehreren Organisationen ist nicht implementiert.

Einrichtung

1. Ein ES256-Schlüsselpaar generieren

Verwenden Sie den modernen genpkey-Befehl – er erzeugt direkt das PKCS#8-Format, das dieser Server benötigt. Der ältere ecparam -genkey erzeugt das SEC1-Format und führt zu einem Startfehler.

# Generate private key (PKCS#8)
openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -out private-key.pem

# Derive public key
openssl pkey -in private-key.pem -pubout -out public-key.pem

Überprüfen Sie, ob der private Schlüssel mit -----BEGIN PRIVATE KEY----- beginnt (nicht -----BEGIN EC PRIVATE KEY-----). Wenn er mit der EC-Variante beginnt, konvertieren Sie ihn:

openssl pkcs8 -topk8 -nocrypt -in ec-key.pem -out private-key.pem

Speichern Sie private-key.pem nach Möglichkeit außerhalb des Repository-Stammverzeichnisses (z. B. ~/.ssh/asa-private-key.pem).

2. Einen API-Benutzer in Apple Search Ads erstellen

1. Gehen Sie zu ASA → Account Settings → User Management

2. Klicken Sie auf Create User, wählen Sie die Rolle API Account Read Only für den schreibgeschützten Zugriff (empfohlen für diesen Server). API Campaign Manager ist ebenfalls in Ordnung und fügt Schreibberechtigungen hinzu, falls Sie den Server später um Schreib-Tools erweitern möchten.

3. Gehen Sie zum Tab API, klicken Sie auf Create Client

4. Laden Sie public-key.pem hoch

5. Kopieren Sie client_id, team_id und key_id vom Bestätigungsbildschirm

6. Finden Sie Ihre org_id unter Account Settings → Overview

3. Klonen und erstellen

git clone https://github.com/andrealufino/aapl-ads-mcp.git
cd aapl-ads-mcp
npm install
npm run build

4. Claude Desktop konfigurieren

Bearbeiten Sie ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "aapl-ads": {
      "command": "node",
      "args": ["/absolute/path/to/aapl-ads-mcp/dist/index.js"],
      "env": {
        "ASA_CLIENT_ID": "SEARCHADS.your-client-id-here",

"ASA_TEAM_ID": "SEARCHADS.your-team-id-here",
"ASA_KEY_ID": "your-key-id-here",
"ASA_ORG_ID": "12345678",
"ASA_PRIVATE_KEY_PATH": "/absolute/path/to/private-key.pem"

} }

} }

Hinweis: ASA_PRIVATE_KEY_PATH muss ein absoluter Pfad sein. Die Tilde (~) wird von Node.js nicht erweitert – verwenden Sie den vollständigen Pfad.

Für Container- oder Cloud-Bereitstellungen, bei denen das Einbinden einer Datei unpraktisch ist, setzen Sie stattdessen ASA_PRIVATE_KEY auf den Inline-PEM-Inhalt (Zeilenumbrüche bleiben erhalten). Wenn beides gesetzt ist, hat ASA_PRIVATE_KEY Vorrang.

Starten Sie Claude Desktop neu. Fragen Sie „run health check“, um zu überprüfen, ob der Server verbunden ist.

Nutzungsbeispiele

Dies sind Prompts in natürlicher Sprache, die mit Claude Desktop funktionieren, sobald der Server läuft:

List my Apple Ads campaigns

Zeige mir die Kampagnenleistung der letzten 30 Tage

Welche Keywords haben letzte Woche in meiner Brand-Kampagne Installationen generiert?

Welche Suchbegriffe haben im letzten Monat meine Anzeigen ausgelöst? Konzentriere dich auf solche mit Impressionen, aber ohne Installationen.

Vergleiche die wöchentlichen Ausgaben über alle Kampagnen für Q1 2025

Zeige Anzeigengruppen in Kampagne 1234567890 mit ihren Gebotsbeträgen

## Development

```bash
npm run build      # compile TypeScript
npm test           # run test suite (Vitest)
npm run typecheck  # type-check without emitting
npm run lint       # Biome lint
npm run format     # Biome format (write)

MCP Inspector

Um Tool-Aufrufe interaktiv ohne Claude Desktop zu debuggen:

npx @modelcontextprotocol/inspector node dist/index.js

Setzen Sie die Umgebungsvariablen in der Inspector-UI, bevor Sie eine Verbindung herstellen.

Pre-commit Hooks

Installieren Sie lefthook-Hooks lokal nach dem Klonen:

npx lefthook install

Dies richtet Folgendes ein:

• gitleaks protect --staged — blockiert Commits, die Geheimnisse enthalten

• Biome-Lint-Prüfung für bereitgestellte .ts-Dateien

• TypeScript-Typenprüfung

Mitwirken

Siehe docs/ARCHITECTURE.md für technische Details: Authentifizierungsfluss, HTTP-Client-Design, Tool-Muster, Besonderheiten des Berichtsschemas und Lektionen aus der ASA v5-Entwicklung.

Fehlerberichte und Pull Requests sind willkommen.

Sicherheit

• Committen Sie niemals .env- oder *.pem-Dateien – beide sind in .gitignore enthalten

• Bewahren Sie private-key.pem außerhalb des Repository-Stammverzeichnisses auf

• Das Zugriffstoken wird nur im Arbeitsspeicher gehalten und niemals auf die Festplatte geschrieben

• Wenn Sie vermuten, dass ein Schlüssel kompromittiert wurde, rotieren Sie ihn unter ASA → Account Settings → API

Lizenz

MIT – siehe LICENSE.