Google Ads MCP

Google Ads MCP ist ein lokaler, sicherheitsorientierter, schreibgeschützter MCP-Server und ein Codex-Plugin zum Untersuchen von Google-Ads-Konten. Version 0.1.0 stellt begrenzte Tools für Inventar, Berichte, Metadaten, Änderungsverlauf und sicheres GAQL bereit. Es enthält keine Schreib-, Upload-, Planungs-, Lösch-, Optimierungs- oder gehosteten Transportfunktionen.

Die öffentliche Python-Distribution heißt google-ads-operator-mcp. Produkt und Befehl bleiben Google Ads MCP und google-ads-mcp.

Sicherheitsgrenze

• Jede kontobezogene Anfrage nennt sowohl ein Profil als auch eine Kunden-ID.

• Google-Anmeldedaten bleiben in Application Default Credentials oder in einer expliziten, nur für den Eigentümer zugänglichen google-ads.yaml außerhalb des Repositorys.

• accounts.json darf nur einen Umgebungsvariablennamen für das Entwickler-Token enthalten, niemals das Token selbst.

• allowWrites muss false sein; jeder andere Wert wird abgelehnt.

• Nur GoogleAdsService, CustomerService und GoogleAdsFieldService werden vom Produktionsadapter instanziiert.

• Ein Tool erhält normalisierte Zeilen, niemals einen Google-Client oder einen rohen Antwortumschlag.

• Im MCP-Modus ist stdout für JSON-RPC reserviert. Diagnosen und bereinigte Fehlercodes gehen an stderr.

Lesen Sie SECURITY.md, PRIVACY.md und das Bedrohungsmodell, bevor Sie ein Produktionskonto verbinden.

Related MCP server: merchant-center-mcp

Anforderungen

• Python 3.11, 3.12 oder 3.13

• uv

• Zugriff auf die Google Ads API mit einem Entwickler-Token

• ADC oder eine separat gespeicherte, nur für den Eigentümer zugängliche google-ads.yaml

Verwenden Sie die offizielle Anleitung von Google für das Entwickler-Token, die Python-Client-Konfiguration und Application Default Credentials.

Lokale Einrichtung

uv sync --frozen --all-groups
uv run --frozen google-ads-mcp version
uv run --frozen google-ads-mcp config init

Nach der öffentlichen Veröffentlichung kann die eigenständige CLI auch mit uv tool install google-ads-operator-mcp==0.1.0 installiert werden. Verwenden Sie für das abschließende Abnahme-Gate für das saubere Plugin das Release-Plugin-Archiv und nicht eine Kopie des Quellbaums.

Bearbeiten Sie ~/.config/google-ads-mcp/accounts.json, ersetzen Sie die öffentlichen Konto-IDs und stellen Sie dann die nur für den Eigentümer zugänglichen Berechtigungen wieder her:

Machen Sie GOOGLE_ADS_DEVELOPER_TOKEN aus Ihrem lokalen Secret-Manager verfügbar, ohne seinen Wert im Repository oder im Chat zu hinterlegen, und führen Sie dann aus:

chmod 600 ~/.config/google-ads-mcp/accounts.json
gcloud auth application-default login
uv run --frozen google-ads-mcp config validate
uv run --frozen google-ads-mcp auth doctor --profile production-read-only

Fügen Sie das Entwickler-Token, das OAuth-Refresh-Token, das Client-Secret, ADC-JSON oder YAML-Inhalte nicht in dieses Repository, in ein Issue, in ein Terminalprotokoll oder in einen Chat ein.

Konfiguration

Die Konfigurationsreihenfolge ist --config, dann GOOGLE_ADS_MCP_CONFIG, dann ~/.config/google-ads-mcp/accounts.json.

{
  "profiles": [
    {
      "name": "production-read-only",
      "loginCustomerId": "1234567890",
      "defaultCustomerId": "0987654321",
      "auth": {
        "type": "adc",
        "developerTokenEnv": "GOOGLE_ADS_DEVELOPER_TOKEN"
      },
      "allowWrites": false
    }
  ]
}

Für ein vorhandenes Google-Client-YAML verwenden Sie {"type":"googleAdsYaml","path":"/absolute/owner-only/google-ads.yaml"}. Relative Pfade und symbolische Links werden abgelehnt. Der Server durchsucht weder das Arbeitsverzeichnis noch das Repository nach YAML-Anmeldedaten.

CLI

google-ads-mcp version
google-ads-mcp config init
google-ads-mcp config validate
google-ads-mcp auth doctor --profile <name>
google-ads-mcp accounts discover --profile <name>
google-ads-mcp serve --stdio

MCP-Tools

Die feste v0.1-API-Oberfläche ist:

auth_check                customers_list
customer_get              customer_hierarchy
account_health            campaigns_query
campaign_inventory        resource_metadata
reports_catalog           report_run
change_events_query       gaql_validate
gaql_search

Typisierte Listen geben höchstens 200 Elemente pro Seite zurück. Ein einzelner Google-Lesevorgang ist auf 1.000 normalisierte Zeilen begrenzt. Fünf-Minuten-Cursor sind an das Profil und die genaue Anfrage gebunden, mit höchstens 20 aktiven Cursorn pro Profil. Sicheres GAQL hat keinen Cursor und erfordert ein einzelnes, kommentarfreies SELECT, eine nicht sensible Ressource und LIMIT 1..1000.

Siehe docs/tools.md für Parameter, Evidenzsemantik und Berichtsverhalten.

Codex-Plugin

Das Repository-Stammverzeichnis ist das Plugin-Stammverzeichnis. .mcp.json ruft ./bin/google-ads-mcp-launcher auf, das nur die eingefrorene uv-Umgebung über stdio ausführt. Das implizite google-ads-operator-Skill behandelt alle Konto-Strings als nicht vertrauenswürdige Daten und schlägt niemals nicht verfügbare Mutations-Tools vor.

Das Repository erstellt oder ändert bewusst keinen persönlichen Marketplace-Eintrag. Die Installation aus dem Release-Archiv wird während der Abnahme separat validiert.

Verifizierung

uv run --frozen ruff check .
uv run --frozen pyright
uv run --frozen pytest
uv run --frozen python scripts/validate_read_only.py
uv run --frozen python scripts/validate_gaql_templates.py
uv run --frozen python ~/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py .
uv run --frozen python ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/google-ads-operator

Automatisierte Verifizierung ist keine Abnahme an einem Live-Konto. Die Gates für das Testkonto und den produktions-schreibgeschützten Zugriff in docs/acceptance.md bleiben vor v0.1.0 erforderlich.

Lizenz

Apache-2.0. Google Ads ist eine Marke von Google LLC. Dieses Projekt ist unabhängig und wird nicht von Google unterstützt.