MCP Google Ads

mcp-google-ads

Servidor MCP de Google Ads multi-cuenta para operadores que necesitan una única superficie MCP en múltiples cuentas de clientes o cuentas publicitarias internas sin reiniciar el servidor.

Estado de publicación: paquete beta, versión 0.1.0 de pyproject.toml.

Elige tu ruta

Eres...	Empieza aquí	Luego
Conectando el servidor a tu cliente MCP	docs/start-here.md	Inicio rápido abajo
Auditando cambio de cuentas y reintentos	docs/architecture.md	gads/server.py
Revisando metadatos de empaquetado	pyproject.toml	accounts.example.json

Arquitectura

flowchart TD
  U[AI operator] --> C[MCP client]
  C --> S[FastMCP server]
  S --> M[Account manager]
  M --> F[Accounts config]
  S --> Q[GAQL query helpers]
  Q --> R[Retry wrapper]
  R --> A[Google Ads API]
  A --> R --> S

Flujo de solicitudes

flowchart TD
  P[Operator asks for account or campaign data] --> T[Selected MCP tool]
  T --> A[Resolve named or default account]
  A --> B[Build Google Ads client]
  B --> C[Run GAQL query]
  C --> D{API call succeeds?}
  D -- yes --> E[Normalize rows and return]
  D -- retryable --> F[Backoff and retry]
  F --> D
  D -- no --> G[Return error payload]

Inicio rápido

1. Instala el paquete.

python -m pip install mcp-google-ads-multi

2. Copia la plantilla de configuración de cuentas y añade tus cuentas.

mkdir -p ~/.config/mcp-google-ads
cp accounts.example.json ~/.config/mcp-google-ads/accounts.json

3. Regístralo en tu cliente MCP.

{
  "mcpServers": {
    "google-ads": {
      "command": "uvx",
      "args": ["mcp-google-ads-multi"],
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "your-developer-token",
        "GOOGLE_ADS_ACCOUNTS_CONFIG": "/Users/you/.config/mcp-google-ads/accounts.json"
      }
    }
  }
}

Herramientas disponibles

Grupo de herramientas	Herramientas	Propósito
Selección de cuenta	list_accounts, set_default_account, list_customers	Gestiona el enrutamiento de cuentas y descubre clientes accesibles
Resumen de gasto	get_account_summary, compare_periods	Informes de cuentas período a período
Análisis de campañas	list_campaigns, get_campaign_performance	Inventario de campañas y métricas basadas en rangos
Detalle a nivel de consulta	get_keyword_performance, search_terms_report, get_ad_performance	Informes de palabras clave, términos de búsqueda y anuncios

Prueba en tiempo de ejecución

Afirmación	Prueba
El punto de entrada del paquete es estable	mcp-google-ads-multi = "gads.server:main" en pyproject.toml
El enrutamiento multi-cuenta es de primera clase	AccountManager() y set_default_account() en gads/server.py
Las consultas pasan por ayudantes reutilizables	gads/query.py y gads/retry.py
La configuración está basada en archivos	accounts.example.json documenta la forma de las cuentas

Mapa del repositorio

Ruta	Propósito
gads/server.py	Superficie de herramientas FastMCP
gads/accounts.py	Configuración de cuentas, carga de OAuth/cuenta de servicio
gads/query.py	Ayudantes de ejecución GAQL
gads/retry.py	Comportamiento de reintentos para llamadas API
docs/start-here.md	Configuración, validación, fallos comunes
docs/architecture.md	Mapa de componentes y ciclo de vida de solicitudes

Validación

Verificación	Comando
La importación compila	python -m compileall gads
El paquete se construye	python -m build
Los enlaces de README/docs son locales	rg '\\]\\(([^)]+\\.md)\\)' README.md docs/

Licencia

MIT

Contexto del proyecto para nuevas tareas

Lee prompt.md, luego INDEX.md, para decisiones específicas del proyecto, rutas de tareas y transferencia actual. Los ejemplos históricos no seleccionan la tarea actual.