aapl-ads-mcp
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: Reddit Ads MCP Server
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,viewInstallsund 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.pemSpeichern 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
Gehen Sie zu ASA → Account Settings → User Management
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.
Gehen Sie zum Tab API, klicken Sie auf Create Client
Laden Sie
public-key.pemhochKopieren Sie
client_id,team_idundkey_idvom BestätigungsbildschirmFinden Sie Ihre
org_idunter 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 build4. 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.jsSetzen 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 installDies richtet Folgendes ein:
gitleaks protect --staged— blockiert Commits, die Geheimnisse enthaltenBiome-Lint-Prüfung für bereitgestellte
.ts-DateienTypeScript-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.gitignoreenthaltenBewahren Sie
private-key.pemaußerhalb des Repository-Stammverzeichnisses aufDas 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.
Available Tools
9 toolsget_ad_group_reportA
Fetch performance metrics for ad groups within a specific Apple Search Ads campaign: impressions, taps, TTR, spend, CPI, installs (tap-through and view-through), and install rate. Requires ASA authentication; read-only. Use get_campaign_report for a campaign-level summary, or get_keyword_report for keyword-level detail. Results are grouped by country/region and include grand totals. Defaults to the last 30 days with WEEKLY granularity.
Inputs: campaignId (required), endDate, startDate, adGroupIds, +1 more.
get_campaign_reportA
Fetch performance metrics for Apple Search Ads campaigns: impressions, taps, tap-through rate (TTR), localSpend, avgCPT, avgCPM, tapInstalls, viewInstalls, totalInstalls, new downloads, redownloads, CPI, and install rate. Requires ASA authentication; read-only. Use get_ad_group_report or get_keyword_report for deeper breakdowns. Results are grouped by country/region and include grand totals. Defaults to the last 30 days with WEEKLY granularity.
Inputs: startDate, endDate, granularity, campaignIds.
get_keyword_reportA
Fetch performance metrics for targeting keywords in a specific Apple Search Ads ad group: impressions, taps, TTR, spend, CPI, installs, and install rate broken down per keyword. Requires ASA authentication; read-only. Use get_search_terms_report to see the actual user queries that triggered these keywords. Results are grouped by country/region and include grand totals. Defaults to the last 30 days with WEEKLY granularity.
Inputs: campaignId (required), adGroupId (required), startDate, endDate, +1 more.
get_search_terms_reportA
Fetch the actual user search queries that triggered Apple Search Ads impressions, along with performance metrics per search term. Requires ASA authentication; read-only. Most useful for keyword discovery (finding new terms to add) and negation (finding irrelevant queries to exclude). Does not support granularity breakdown — returns aggregate totals per search term. Use get_keyword_report to see metrics for your configured targeting keywords instead. Defaults to the last 30 days.
Inputs: campaignId (required), adGroupId (required), startDate, endDate, +1 more.
healthA
Check if the aapl-ads-mcp server is running and reachable. Use this to verify the MCP connection before making API calls. No ASA authentication is required — returns server name, version, and current timestamp.
Inputs: no named parameters.
list_ad_groupsA
List ad groups within a specific Apple Search Ads campaign. Requires ASA authentication; read-only. Returns ad group metadata (id, name, status, default bid, automated keyword opt-in) but not performance metrics — use get_ad_group_report for metrics. Supports pagination via limit/offset; default limit 20, max 1000.
Inputs: campaignId (required), limit, offset.
list_campaignsA
List all campaigns in the configured Apple Search Ads organization. Requires ASA authentication; read-only. Returns campaign metadata (id, name, status, budget, country, channel type) but not performance metrics — use get_campaign_report for metrics. Optionally filter by status. Supports pagination via limit/offset; default limit 20, max 1000.
Inputs: status, limit, offset.
list_keywordsA
List targeting keywords for a specific Apple Search Ads ad group. Requires ASA authentication; read-only. Returns keyword metadata (text, match type BROAD/EXACT, bid amount, status) but not performance metrics — use get_keyword_report for metrics. Supports pagination via limit/offset; default limit 20, max 1000.
Inputs: campaignId (required), adGroupId (required), limit, offset.
list_orgsA
List all Apple Search Ads organizations accessible with the configured credentials. Requires ASA authentication. Use this to verify credentials are valid and to discover available org IDs before calling other tools. Returns org ID, name, currency, timezone, payment model, and assigned role names.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool targets a distinct entity and action: list_* for enumerating hierarchy levels, get_*_report for metrics at each level, get_search_terms_report for search queries, and health for server status. No two tools could be confused for the same task.
Most tools follow the list_ or get_*_report pattern clearly separating metadata enumeration from report retrieval. The single deviation is 'health', which is a noun rather than a verb-prefixed action (e.g., check_health), making the pattern slightly inconsistent.
Nine tools is well-scoped for a read-only Apple Search Ads data access server: four list tools for entity hierarchy, four report tools for metrics breakdowns, and a health check. Each tool serves a distinct need without redundancy.
The read-only surface covers the full object hierarchy (org → campaign → ad group → keyword) with list operations and corresponding report endpoints, including search terms. However, the complete absence of write operations (no create/update/delete for campaigns or keywords) could be a gap if management tasks are expected, though it appears intentionally read-only.
Maintenance
Related MCP Connectors
Read your Amazon Ads campaigns, results, rules and activity, every marketplace and ad type.
Manage Apple Ads campaigns and reporting in chat.
Read-only Google Ads, Meta Ads and TikTok Ads performance, campaigns and creatives via OAuth.
Google Ads reporting and reviewable change plans using your own Google authorization.
1
Related MCP Servers
- AlicenseBqualityCmaintenanceProvides read-only access to TikTok advertising data, including campaigns, ad groups, ads, and performance reports through the TikTok Business API.672 PyPI46MIT
- FlicenseNot gradedqualityDmaintenanceRead-only access to Reddit Ads API v3 for listing ad accounts, campaigns, ad groups, ads, and generating performance reports with OAuth2 authentication.-
- AlicenseNot gradedqualityBmaintenanceEnables read-only analysis of Apple Ads Platform data, allowing AI assistants to query campaign structure, keywords, search terms, and performance reports without modifying anything.MIT
- AlicenseNot gradedqualityDmaintenanceProvides read-only tools for Reddit Ads, listing accounts, campaigns, ad groups, ads, and generating performance reports.1MIT