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

Servidor MCP local que expone datos de rendimiento, configuración de campañas e historial de cambios de Google Ads + Meta Marketing a Claude (Cowork) para flujos de trabajo de paneles diarios en tiempo real.

Qué hace

Tres herramientas registradas con MCP:

Herramienta	Propósito
`get_google_ads_report(date_range, breakdown)`	Rendimiento + diagnósticos + series de 56 días + WoW + comparaciones de 8 semanas DoW + configuración de campañas + historial de cambios
`get_meta_ads_report(date_range, breakdown)`	Misma estructura que Google. Conversiones filtradas a `META_CONVERSION_EVENT_NAME`
`get_campaign_settings(platform)`	Configuración + historial de cambios para `google` / `meta` / `both`

Arquitectura: extrae datos brutos de anuncios por día una vez por plataforma cada hora, los almacena en caché en formato parquet y deriva cada agregación en pandas. Sin llamadas a la API por desglose.

Related MCP server: mcp-marketing-analytics

Requisitos previos

macOS / Linux
Python 3.13 (se recomienda usar pyenv)
Gestor de paquetes uv: brew install uv
Acceso a la API de Google Ads — ver Google Ads API getting started
Acceso a la API de Meta Marketing — ver Marketing API getting started

Enlaces de configuración de credenciales

Credencial	Dónde obtenerla
`GOOGLE_ADS_DEVELOPER_TOKEN`	Interfaz de Google Ads → Herramientas → Centro de API
`GOOGLE_ADS_CLIENT_ID` / `CLIENT_SECRET`	https://console.cloud.google.com → Cliente OAuth 2.0 (Aplicación de escritorio)
`GOOGLE_ADS_REFRESH_TOKEN`	Ejecutar `python -m google.ads.googleads.examples.authentication.generate_user_credentials` después de instalar `google-ads`
`GOOGLE_ADS_CUSTOMER_IDS`	Separados por comas, sin guiones. Encontrarlos en la parte superior derecha de la interfaz de Google Ads
`GOOGLE_ADS_LOGIN_CUSTOMER_ID`	ID de la cuenta de administrador MCC, sin guiones
`META_APP_ID` / `META_APP_SECRET`	https://developers.facebook.com → Mis aplicaciones → Configuración → Básico
`META_ACCESS_TOKEN`	https://business.facebook.com → Configuración del negocio → Usuarios del sistema → Generar nuevo token (de larga duración, con `ads_read`)
`META_AD_ACCOUNT_ID`	Administrador de anuncios de Meta → selector de cuenta superior izquierda. Formato: `act_XXXXXXXXX`

Instalación

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

uv crea .venv/ e instala todas las dependencias fijadas en pyproject.toml.

Configurar credenciales

Dos opciones:

Opción A — apuntar a un .env existente (recomendado si ya tienes claves en ~/marketing-ds/decision_science/.env):

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

Opción B — .env local:

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

Las claves requeridas se enumeran en .env.example con comentarios que explican cada una.

Ejecución

Localmente para pruebas:

uv run ads-mcp-server

El servidor habla MCP a través de stdio — Cowork (o cualquier cliente MCP) lo inicia bajo demanda.

Conectar a Claude (Cowork)

Añade este bloque a ~/.claude/claude_desktop_config.json (créalo si no existe):

{
  "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"
      }
    }
  }
}

Reinicia Claude/Cowork. Deberían aparecer las herramientas get_google_ads_report, get_meta_ads_report, get_campaign_settings.

No se requiere un demonio en segundo plano — Cowork inicia/detiene el proceso por sesión.

Precalentamiento diario (recomendado para paneles en tiempo real)

Regla de validez de caché: una caché está actualizada si contiene la fecha de ayer. Se actualiza una vez al día. La primera consulta del usuario del día activa la actualización — y una extracción de 56 días en una cuenta grande puede tardar de 1 a 3 minutos.

Para evitar esa espera, programa un precalentamiento a las 6 a.m. mediante launchd de macOS:

# 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

Lo que hace cada mañana a las 6 a.m.:

Extrae el rendimiento de Google Ads de 56 días, configuración, change_event de 29 días → caché
(Meta actualmente deshabilitado — ver "Estado de Meta" a continuación)
Escribe la marca de actualización cache/google_lastrefresh.txt = hoy

Para cuando abras Cowork, los datos de Google estarán listos. Las llamadas a las herramientas responden en menos de 1s.

Para desinstalar:

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

Estado de Meta (a fecha de 2026-05-07)

Las herramientas de Meta (get_meta_ads_report, get_campaign_settings(platform="meta"|"both")) están estructuralmente completas pero aún no verificadas de extremo a extremo.

Lo que funciona:

La extracción de rendimiento se divide en ventanas de 7 días (evita el error "result too large" Service temporarily unavailable / subcode 1504044)
Los datos a nivel de anuncio están divididos: level=campaign para la serie de 56 días, level=ad solo para ayer (evita la paginación de 5 minutos)
La extracción de AdSet se filtra a effective_status IN [ACTIVE, PAUSED] (evita paginar miles de conjuntos de anuncios archivados)

Lo que nos bloqueó:

Después de la primera gran extracción de rendimiento, la extracción de AdSet alcanzó el límite de tasa por hora de Meta (code 17, subcode 2446079: "User request limit reached"). El tiempo de espera suele ser de 10 a 60 minutos.

Para volver a probar mañana por la mañana (después de que se restablezca la cuota):

# 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

Si Meta sigue limitando la tasa, opciones alternativas (aún no implementadas):

Ejecuciones de informes asíncronos (async=True) para la extracción de rendimiento
Filtro effective_status más estricto (solo ACTIVE, descartar pausados)

Si prefieres un proceso en segundo plano de larga duración (opcional, no requerido para Cowork): usa nohup uv run ads-mcp-server > /tmp/ads-mcp.log 2>&1 & o un plist de launchd.

Opcional: anulación mediante CSV (saltar la API)

La interfaz de Google Ads exporta informes CSV sin límites de cuota de API. Coloca un CSV en cache/external/ para anular la extracción de la API:

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

Si existe un CSV coincidente Y es más reciente que la caché de parquet, el servidor lo carga en lugar de llamar a la API. La respuesta establece metadata.data_source = "csv_override" para que Cowork lo sepa.

El esquema de columnas del CSV debe coincidir con el de parquet (consulta src/ads_mcp_server/google_ads.py y meta_ads.py para los nombres de las columnas: date, campaign_id, campaign_name, ad_id, ad_name, spend, impressions, clicks, conversions, ...).

Pruebas

uv run pytest -v

Todas las pruebas están basadas en mocks — no hay llamadas de red. Cubre:

classify_campaign Marca/No-Marca/Otro
diagnose clasificador de 5 estados
El selector de 8 semanas del mismo día de la semana elige las 8 fechas correctas
Delta WoW + división por cero
Filtro actions[] para Meta
Diferencia de instantánea incluyendo valor nulo-antiguo y poda
Las credenciales faltantes devuelven un error limpio (sin excepción)

Registros

Cada llamada a la API y error se registra en logs/YYYY-MM-DD.log (un archivo por día).

Solución de problemas

La instalación de google-ads falla: asegúrate de que Python 3.13 (uv python pin 3.13) y pip install grpcio funcionen en tu sistema. En Apple Silicon: arch -arm64 uv sync.
Token de Meta expirado: regenera el token de usuario del sistema en la Configuración del negocio; los tokens de larga duración duran 60 días.
La herramienta no aparece en Cowork: revisa ~/Library/Logs/Claude/mcp*.log para ver errores de inicio. Confirma que uv está en el PATH para el proceso de la GUI (puede que necesites una ruta completa: which uv).
Caché obsoleta: elimina cache/*.parquet para forzar una nueva extracción.

Mapa de archivos

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
1421
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

Qué hace

Requisitos previos

Enlaces de configuración de credenciales

Instalación

Configurar credenciales

Ejecución

Conectar a Claude (Cowork)

Precalentamiento diario (recomendado para paneles en tiempo real)

Estado de Meta (a fecha de 2026-05-07)

Opcional: anulación mediante CSV (saltar la API)

Pruebas

Registros

Solución de problemas

Mapa de archivos

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