ads-mcp-server

Lokaler MCP-Server, der Google Ads- und Meta Marketing-Leistungsdaten, Kampagneneinstellungen und Änderungshistorien für Claude (Cowork) für tägliche Live-Dashboard-Workflows bereitstellt.

Funktionsweise

Drei Tools sind bei MCP registriert:

Architektur: Abruf der Rohdaten (Anzeigen × Tag) einmal pro Plattform pro Stunde, Zwischenspeicherung in Parquet, Ableitung aller Aggregationen in Pandas. Kein API-Aufruf pro Aufschlüsselung.

Related MCP server: Google Ads MCP Server

Voraussetzungen

• macOS / Linux

• Python 3.13 (via pyenv empfohlen)

• uv Paketmanager: brew install uv

• Google Ads API-Zugriff — siehe Google Ads API Erste Schritte

• Meta Marketing API-Zugriff — siehe Marketing API Erste Schritte

Links zur Einrichtung der Anmeldedaten

Installation

cd ~/marketing-ds/ads-mcp-server
uv sync --extra dev

uv erstellt .venv/ und installiert alle in pyproject.toml fixierten Abhängigkeiten.

Anmeldedaten konfigurieren

Zwei Optionen:

Option A — auf bestehende .env verweisen (empfohlen, falls Sie bereits Schlüssel in ~/marketing-ds/decision_science/.env haben):

export ADS_MCP_ENV_FILE=/Users/jmacaggi/marketing-ds/decision_science/.env

Option B — lokale .env:

cp .env.example .env
# fill in the blanks

Erforderliche Schlüssel sind in .env.example mit Kommentaren zu jedem Eintrag aufgelistet.

Ausführen

Lokal zum Testen:

uv run ads-mcp-server

Der Server spricht MCP über stdio — Cowork (oder jeder MCP-Client) startet ihn bei Bedarf.

Mit Claude (Cowork) verbinden

Fügen Sie diesen Block zu ~/.claude/claude_desktop_config.json hinzu (erstellen, falls nicht vorhanden):

{
  "mcpServers": {
    "ads": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/jmacaggi/marketing-ds/ads-mcp-server",
        "run",
        "ads-mcp-server"
      ],
      "env": {
        "ADS_MCP_ENV_FILE": "/Users/jmacaggi/marketing-ds/decision_science/.env"
      }
    }
  }
}

Starten Sie Claude/Cowork neu. Die Tools get_google_ads_report, get_meta_ads_report und get_campaign_settings sollten erscheinen.

Kein Hintergrund-Daemon erforderlich — Cowork startet/stoppt den Prozess pro Sitzung.

Tägliches Vorwärmen (empfohlen für Live-Dashboard)

Cache-Gültigkeitsregel: Ein Cache ist aktuell, wenn er das Datum von gestern enthält. Aktualisierung einmal täglich. Die erste Benutzerabfrage des Tages löst die Aktualisierung aus — und ein 56-Tage-Abruf bei einem großen Konto kann 1-3 Minuten dauern.

Um diese Wartezeit zu vermeiden, planen Sie ein Vorwärmen um 6 Uhr morgens über macOS launchd:

# Install
cp /Users/jmacaggi/marketing-ds/ads-mcp-server/launchd/com.jmacaggi.adsmcp.prewarm.plist \
   ~/Library/LaunchAgents/

launchctl load ~/Library/LaunchAgents/com.jmacaggi.adsmcp.prewarm.plist

# Verify it's scheduled
launchctl list | grep adsmcp

# Trigger immediately (test)
launchctl start com.jmacaggi.adsmcp.prewarm

# Logs
tail -f ~/marketing-ds/ads-mcp-server/logs/prewarm.stdout.log
tail -f ~/marketing-ds/ads-mcp-server/logs/$(date +%Y-%m-%d).log

Was jeden Morgen um 6 Uhr passiert:

1. Abruf Google Ads Leistung 56d, Einstellungen, change_event 29d → Cache

2. (Meta derzeit deaktiviert — siehe "Meta-Status" unten)

3. Schreibt Aktualisierungsstempel cache/google_lastrefresh.txt = heute

Wenn Sie Cowork öffnen, sind die Google-Daten bereits geladen. Tool-Aufrufe erfolgen in <1s.

Zum Deinstallieren:

launchctl unload ~/Library/LaunchAgents/com.jmacaggi.adsmcp.prewarm.plist
rm ~/Library/LaunchAgents/com.jmacaggi.adsmcp.prewarm.plist

Meta-Status (Stand 07.05.2026)

Meta-Tools (get_meta_ads_report, get_campaign_settings(platform="meta"|"both")) sind strukturell vollständig, aber noch nicht durchgehend verifiziert.

Was funktioniert:

• Der Leistungsabruf ist in 7-Tage-Fenster unterteilt (vermeidet den Fehler "Service temporarily unavailable / subcode 1504044" "result too large")

• Daten auf Anzeigenebene sind aufgeteilt: level=campaign für die 56-Tage-Reihe, level=ad nur für gestern (vermeidet 5-minütige Paginierung)

• Der AdSet-Abruf ist gefiltert auf effective_status IN [ACTIVE, PAUSED] (vermeidet das Paginieren von Tausenden archivierter Anzeigengruppen)

Was uns blockiert hat:

• Nach dem ersten großen Leistungsabruf stieß der AdSet-Abruf auf das stündliche Ratenlimit von Meta (code 17, Subcode 2446079: "User request limit reached"). Die Abklingzeit beträgt normalerweise 10-60 Minuten.

Zum erneuten Testen morgen früh (nachdem das Kontingent zurückgesetzt wurde):

# Remove --skip-meta from the launchd plist to enable Meta in pre-warm
sed -i '' '/<string>--skip-meta<\/string>/d' \
   ~/Library/LaunchAgents/com.jmacaggi.adsmcp.prewarm.plist
launchctl unload ~/Library/LaunchAgents/com.jmacaggi.adsmcp.prewarm.plist
launchctl load ~/Library/LaunchAgents/com.jmacaggi.adsmcp.prewarm.plist

# Or run manually
ADS_MCP_ENV_FILE=/Users/jmacaggi/marketing-ds/decision_science/.env \
   uv run python scripts/prewarm.py

Falls Meta weiterhin Ratenbegrenzungen erzwingt, Fallback-Optionen (noch nicht implementiert):

• Asynchrone Berichtsausführungen (async=True) für den Leistungsabruf

• Strengerer effective_status-Filter (nur ACTIVE, pausierte ausschließen)

Wenn Sie einen langlebigen Hintergrundprozess bevorzugen (optional, für Cowork nicht erforderlich): verwenden Sie nohup uv run ads-mcp-server > /tmp/ads-mcp.log 2>&1 & oder eine launchd-plist.

Optional: CSV-Überschreibung (API überspringen)

Die Google Ads UI exportiert CSV-Berichte ohne API-Kontingentbeschränkungen. Legen Sie eine CSV in cache/external/ ab, um den API-Abruf zu überschreiben:

cache/external/google_2026-05-07.csv
cache/external/meta_2026-05-07.csv

Wenn eine passende CSV existiert UND neuer ist als der Parquet-Cache, lädt der Server diese anstelle des API-Aufrufs. Die Antwort setzt metadata.data_source = "csv_override", damit Cowork dies erkennt.

Das CSV-Spaltenschema muss mit dem Parquet übereinstimmen (siehe src/ads_mcp_server/google_ads.py und meta_ads.py für Spaltennamen: date, campaign_id, campaign_name, ad_id, ad_name, spend, impressions, clicks, conversions, ...).

Test

uv run pytest -v

Alle Tests basieren auf Mocks — keine Netzwerkaufrufe. Deckt ab:

• classify_campaign Marke/Keine Marke/Sonstiges

• diagnose 5-Zustands-Klassifikator

• 8-Wochen-gleicher-Wochentag-Selektor wählt die richtigen 8 Daten aus

• WoW-Delta + Division durch Null

• actions[]-Filter für Meta

• Snapshot-Diff inklusive Null-Altwert und Bereinigung

• Fehlende Anmeldedaten geben sauberen Fehler zurück (keine Exception)

Protokolle

Jeder API-Aufruf und Fehler wird in logs/YYYY-MM-DD.log protokolliert (eine Datei pro Tag).

Fehlerbehebung

• google-ads-Installation schlägt fehl: Stellen Sie sicher, dass Python 3.13 (uv python pin 3.13) und pip install grpcio auf Ihrem System funktionieren. Auf Apple Silicon: arch -arm64 uv sync.

• Meta-Token abgelaufen: Generieren Sie das Systembenutzer-Token in den Unternehmenseinstellungen neu; langlebige Token halten 60 Tage.

• Tool erscheint nicht in Cowork: Überprüfen Sie ~/Library/Logs/Claude/mcp*.log auf Startfehler. Bestätigen Sie, dass uv im PATH für den GUI-Prozess vorhanden ist (Sie benötigen möglicherweise einen vollständigen Pfad: which uv).

• Cache veraltet: Löschen Sie cache/*.parquet, um einen frischen Abruf zu erzwingen.

Dateistruktur

src/ads_mcp_server/
  server.py        # MCP entry + tool handlers
  config.py        # env loading, validates creds
  google_ads.py    # 3 GAQL queries: perf, settings, change_event
  meta_ads.py      # Insights + AdSet pull
  snapshots.py     # Meta snapshot diff (Meta has no reliable change API)
  cache.py         # parquet + CSV override
  aggregate.py     # all pandas math
  classify.py      # Brand/NB/Other
  diagnose.py      # 5-state diagnosis
  date_ranges.py   # window resolution + 8wk DoW
  retry.py         # exponential backoff
  logging_setup.py # daily file logs
  schema.py        # response shape constants