de en es ja ko ru zh

ads-mcp-server

Name: ads-mcp-server
Author: jmacaggi-gfm

by jmacaggi-gfm

Overview Schema Source Related Servers Discussions Admin

Python

Local

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:

Tool	Zweck
`get_google_ads_report(date_range, breakdown)`	Leistung + Diagnosen + 56-Tage-Reihe + WoW + 8-Wochen-DoW-Vergleiche + Kampagneneinstellungen + Änderungshistorie
`get_meta_ads_report(date_range, breakdown)`	Gleiche Struktur wie Google. Conversions gefiltert nach `META_CONVERSION_EVENT_NAME`
`get_campaign_settings(platform)`	Einstellungen + Änderungshistorie für `google` / `meta` / `both`

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: mcp-marketing-analytics

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

Anmeldedaten	Bezugsquelle
`GOOGLE_ADS_DEVELOPER_TOKEN`	Google Ads UI → Tools → API-Center
`GOOGLE_ADS_CLIENT_ID` / `CLIENT_SECRET`	https://console.cloud.google.com → OAuth 2.0-Client (Desktop-App)
`GOOGLE_ADS_REFRESH_TOKEN`	Führen Sie `python -m google.ads.googleads.examples.authentication.generate_user_credentials` nach der Installation von `google-ads` aus
`GOOGLE_ADS_CUSTOMER_IDS`	Kommagetrennt, ohne Bindestriche. Zu finden in der Google Ads UI oben rechts
`GOOGLE_ADS_LOGIN_CUSTOMER_ID`	MCC-Manager-Konto-ID, ohne Bindestriche
`META_APP_ID` / `META_APP_SECRET`	https://developers.facebook.com → Meine Apps → Einstellungen → Basis
`META_ACCESS_TOKEN`	https://business.facebook.com → Unternehmenseinstellungen → Systembenutzer → Neuen Token generieren (langlebig, mit `ads_read`)
`META_AD_ACCOUNT_ID`	Meta Ads Manager → Kontowähler oben links. Format: `act_XXXXXXXXX`

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:

Abruf Google Ads Leistung 56d, Einstellungen, change_event 29d → Cache
(Meta derzeit deaktiviert — siehe "Meta-Status" unten)
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

Available Tools

3 tools

get_campaign_settingsC

Current campaign settings + 56-day change history per platform.

ParametersJSON Schema

Name	Required	Description	Default
`platform`	Yes

TDQS

C2.4/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must fully convey behavioral traits. It discloses that the tool returns both settings and a 56-day history, but does not indicate whether it is read-only, any authentication needs, rate limits, or what triggers destructive actions. The behavior is partially described but lacks completeness.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, making it very concise, but it omits important details such as parameter semantics and usage context. Conciseness is achieved at the expense of completeness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter, no output schema, no annotations), the description is insufficient. It does not explain the output structure, whether the data is aggregated per platform, or provide examples. The lack of detail makes it hard for an AI agent to fully understand the tool's capabilities.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has one parameter 'platform' with enum values, but the description does not explain the parameter's meaning beyond 'per platform'. It fails to clarify what 'both' implies or how the parameter affects the output. With 0% schema description coverage, the description adds no value over the schema itself.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves 'current campaign settings + 56-day change history per platform', which is a specific verb+resource. However, it does not explicitly differentiate itself from sibling tools like get_google_ads_report or get_meta_ads_report, which are focused on ads reports rather than settings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives such as get_google_ads_report or get_meta_ads_report. It does not mention exclusion criteria or context for usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_google_ads_reportA

Pull Google Ads performance. Returns account totals, campaign-type breakdown, top-50 per-ad rows with diagnosis, 56-day daily series, and WoW + 8-week DoW comparisons. Set include_campaign_settings=True to also return per-campaign settings (target CPA, daily budget, diagnosis, utilization) for ENABLED campaigns only.

ParametersJSON Schema

Name	Required	Description
`date_range`	Yes
`breakdown`	Yes
`include_campaign_settings`	No	If true, attach campaign_settings list to the response. Defaults to false to keep payload small.

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, but the description details return components and the conditional behavior of include_campaign_settings (only for ENABLED campaigns).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three concise sentences, no fluff, front-loaded with purpose and outputs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Description covers essential behavioral and parameter details despite lack of output schema; minor gaps in rate limits or authentication info.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is low (33%), but the description adds meaning to parameters by linking them to return elements (e.g., 'campaign-type breakdown' for breakdown enum).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Pull Google Ads performance' and lists specific outputs, distinguishing it from siblings like get_meta_ads_report and get_campaign_settings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies its use for Google Ads performance but does not explicitly guide when to use this tool over siblings or provide exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_meta_ads_reportB

Pull Meta Ads performance. Same shape as get_google_ads_report. Conversions filtered to META_CONVERSION_EVENT_NAME.

ParametersJSON Schema

Name	Required	Description	Default
`date_range`	Yes
`breakdown`	Yes

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It only mentions the output shape similarity and a conversion filter, but lacks details on side effects, rate limits, authentication needs, or other behavioral traits. This is minimal disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise with two short sentences, each providing distinct value. It front-loads the key information and avoids fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description should explain the report contents. It mentions a conversion filter but does not list other metrics or describe the full structure. Relying on the shape of get_google_ads_report is insufficient without that tool's description being present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description should add meaning to parameters. It does not explain the 'date_range' or 'breakdown' parameters beyond their enum values, which are self-explanatory but not enriched. This is a significant gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The name and description clearly indicate this tool retrieves Meta Ads performance data. The verb 'Pull' is specific, and the description explicitly states it is analogous to get_google_ads_report, which distinguishes it from sibling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by comparing to get_google_ads_report, but does not provide explicit guidance on when to use this tool versus alternatives or any prerequisites. No exclusions or when-not-to-use information is given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

3 tool updatesv0.1.0May 8, 2026
- First observedget_campaign_settings
- First observedget_google_ads_report
- First observedget_meta_ads_report

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.2/5.0

Scored 2026-05-08 03:10 across 3 tools

Disambiguation5/5

Each tool targets a distinct area: campaign settings, Google Ads performance, and Meta Ads performance. No overlap; descriptions clearly differentiate them.

Naming Consistency5/5

All tool names follow a consistent 'get_' prefix with the specific resource (campaign_settings, google_ads_report, meta_ads_report). Consistent snake_case pattern.

Tool Count4/5

Three tools is minimal but appropriate for a focused ads reporting and settings retrieval server. Could be expanded but current count is reasonable for the stated purpose.

Completeness2/5

Only read operations are exposed; no create, update, or delete tools for campaigns or ads. Significant gaps for a full ads management workflow.

Maintenance

ActivityStale

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

Jepto AOAuth
com.jepto
Live Google Ads, GA4, Search Console, Meta Ads and GBP data in Claude, ChatGPT and any MCP client
Data Visualization Marketing
142
mcp-serverOAuth
co.flyweel
Access Google & Meta Ads data via AI. Analyse campaign performance in seconds.
Marketing Search Data Platforms
2
AttachéOAuth
studio.attache
GA4, Google Ads and Search Console in Claude. Read-only OAuth, multi-account for agencies.
Marketing Customer Data Platforms
1
LoomaScale AdsOAuth
com.loomascale
Run Google Ads and Meta Ads from ChatGPT or Claude: audit wasted spend, create and manage campaigns.
Marketing Social Media App Automation
11

Related MCP Servers

Google Ads MCP Server
Marketing Search
jgdeutsch
A
license
Not graded
quality
D
maintenance
Provides access to Google Ads API for comprehensive campaign analytics, enabling conversational ad performance analysis with Claude Code.
Updated 8 months ago (2026-02-16 18:11 UTC)
25 npm
2
MIT
mcp-marketing-analytics
Marketing Search
christophertanenso
F
license
A
quality
D
maintenance
Enables natural language querying of Google Analytics 4, Google Search Console, Meta Ads, and Google Ads data through Claude.
Updated 8 months ago (2026-02-26 07:04 UTC)
23
-
OQVA Marketing MCPofficial
Marketing Social Media
oqva-digital
A
license
A
quality
B
maintenance
Connect Claude to your marketing data from Google and Meta, enabling read and write operations on Search Console, Analytics, Tag Manager, Business Profile, and Meta platforms.
Updated 22 days ago (2026-09-24 14:01 UTC)
35
Apache 2.0
Meta Ads MCP Server
Marketing Data Platforms Monitoring
asm-2023
A
license
Not graded
quality
D
maintenance
Enables Claude to fetch and analyze Meta ad accounts, campaigns, ad sets, ads, and performance insights via the Meta Marketing API.
Updated 3 months ago (2026-07-04 20:23 UTC)
1,621 npm
MIT

ads-mcp-server

Funktionsweise

Voraussetzungen

Links zur Einrichtung der Anmeldedaten

Installation

Anmeldedaten konfigurieren

Ausführen

Mit Claude (Cowork) verbinden

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

Meta-Status (Stand 07.05.2026)

Optional: CSV-Überschreibung (API überspringen)

Test

Protokolle

Fehlerbehebung

Dateistruktur

Available Tools

TDQS

TDQS

TDQS

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Google Ads MCP Server

mcp-marketing-analytics

OQVA Marketing MCPofficial

Meta Ads MCP Server