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:

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: Google Ads MCP Server

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

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.:

1. Extrae el rendimiento de Google Ads de 56 días, configuración, change_event de 29 días → caché

2. (Meta actualmente deshabilitado — ver "Estado de Meta" a continuación)

3. 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