Servidor de MCP de Google Ads: Guía de integración para desarrolladores

El Protocolo de contexto del modelo (MCP) es un estándar abierto que permite que los modelos de lenguaje grandes (LLM) interactúen de forma segura con datos y aplicaciones externos. El servidor de MCP de Google Ads proporciona un puente estandarizado a la API de Google Ads, lo que permite que los agentes de IA analicen y recuperen datos de campañas con lenguaje natural.

Recursos y asistencia de la comunidad

Descripción técnica general

Si implementas este servidor de MCP, eliminas la necesidad de escribir "código de unión" personalizado para la autenticación de la API de Google Ads, la recuperación de recursos y el análisis de datos. El servidor expone herramientas específicas que un LLM puede descubrir e invocar de forma autónoma.

Especificaciones clave

  • Protocolo: MCP (Protocolo de contexto del modelo)
  • Modo: Solo lectura (versión actual)
  • Lenguaje: Python
  • Transporte: Entrada y salida estándar (stdio) o HTTP transmitible (streamable-http/Cloud Run)
  • Autenticación: OAuth 2.0 o cuenta de servicio

Cómo funciona el bucle de interacción

  1. Solicitud: Un usuario envía una consulta como "¿Cómo es el rendimiento de mi campaña esta semana?".
  2. Descubrimiento: El LLM inspecciona sus herramientas disponibles y, luego, identifica las capacidades de búsqueda de google-ads-mcp.
  3. Ejecución: El servidor de MCP ejecuta la lógica de Python subyacente para consultar la API de Google Ads.
  4. Inserción de contexto: Los resultados estructurados se devuelven a la ventana de contexto del LLM.
  5. Respuesta: El LLM sintetiza los datos en una respuesta legible por humanos.

Comenzar

Sigue estos pasos para configurar y usar el servidor de MCP de Google Ads.

Requisitos previos

Antes de la configuración, asegúrate de tener las siguientes credenciales de la consola de Google Cloud:

  • ID del proyecto: Es el ID de tu proyecto de Google Cloud (GOOGLE_PROJECT_ID). Consulta la página Resumen de la API de Google Ads para asegurarte de que tu proyecto tenga niveles de acceso de explorador, básico o acceso estándar. De lo contrario, solicita uno de estos niveles de acceso. Ten en cuenta que los tokens de desarrollador (GOOGLE_ADS_DEVELOPER_TOKEN) dejaron de estar disponibles el 9 de septiembre de 2026 y ya no son necesarios en la versión más reciente del servidor de MCP de Google Ads, ya que los niveles de acceso a la API están asociados con el proyecto de Google Cloud.
  • Credenciales de OAuth: Un par de ID de cliente/secreto del cliente de OAuth 2.0 o un conjunto de credenciales predeterminadas de la aplicación.

Configuración

Para integrar el servidor en un host compatible con MCP, agrega la siguiente entrada al archivo de configuración de MCP de tu host, como settings.json, y apunta GOOGLE_APPLICATION_CREDENTIALS a tu archivo JSON de ADC (o configura las ADC predeterminadas con gcloud auth application-default login). Si accedes a las cuentas a través de una cuenta de administrador, también puedes configurar GOOGLE_ADS_LOGIN_CUSTOMER_ID. Consulta la documentación de tu host para conocer la ubicación exacta y el nombre de archivo de esta configuración.

{
  "mcpServers": {
    "google-ads-mcp": {
      "command": "pipx",
      "args": [
        "run",
        "--spec",
        "git+https://github.com/googleads/google-ads-mcp.git",
        "google-ads-mcp"
      ],
      "env": {
        "GOOGLE_PROJECT_ID": "YOUR_PROJECT_ID",
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/credentials.json"
      }
    }
  }
}

Opcional: Equipa a tu agente con habilidades y el asistente para desarrolladores

El servidor de MCP de Google Ads le otorga a tu cliente de IA acceso de solo lectura a los datos de la cuenta en tiempo real. Para ayudar a tu agente a construir consultas válidas en el lenguaje de consulta de Google Ads (GAQL), diagnosticar cambios en el rendimiento de la cuenta y generar código de biblioteca cliente, vincula el servidor de MCP con estas herramientas complementarias:

  • Habilidades del agente de la API de Google Ads: Son módulos portátiles de instrucciones y flujos de trabajo específicos de la API de Google Ads, incluidos google-ads-api-mcp-setup, google-ads-api-account-diagnostics y google-ads-api-quickstart, que le enseñan a tu agente a usar el servidor de MCP de Google Ads de forma eficaz con una menor sobrecarga de tokens. Instálalas con un solo comando (requiere Node.js) o consulta la guía de habilidades de agentes de la API de Google Ads para conocer las opciones de Antigravity, Claude Code, Codex y Cursor:

    npx skills add google/skills/skills/ads

  • Asistente para desarrolladores de la API de Google Ads: Es un complemento modular para Google Antigravity y Claude Code que proporciona inspección de esquemas de Protobuf locales, validación programática de GAQL, generación de código de biblioteca cliente (incluidos secuencias de comandos de mutación) y solución de problemas de conversiones sin conexión. Obtén información sobre cómo funciona en ¿Qué es el Asistente para desarrolladores de la API de Google Ads? o sigue la guía de instalación.

Implementación en Google Cloud

En lugar de alojar este servidor de MCP de forma local, puedes alojarlo en Google Cloud Run o en cualquier otra infraestructura basada en la nube. Esto es útil si deseas compartir el servidor entre diferentes agentes o ejecutarlo como un servicio web.

Requisitos previos

  1. Un proyecto de Google Cloud,

  2. La herramienta de línea de comandos de gcloud instalada, autenticada y con un proyecto activo configurado:

    gcloud config set project YOUR_PROJECT_ID

Compila y envía una imagen de Docker

Puedes usar Cloud Build para compilar y enviar la imagen a Artifact Registry sin necesidad de instalar Docker de forma local.

  1. Crea un repositorio en Artifact Registry:

    gcloud artifacts repositories create mcp-servers \
  --repository-format=docker --location=us-central1

  2. Ve al directorio del proyecto:

    cd <full path>/google-ads-mcp

  3. Compila y envía la imagen:

    gcloud builds submit \
  --tag us-central1-docker.pkg.dev/YOUR_PROJECT_ID/mcp-servers/google-ads-mcp:latest .

    Ten en cuenta que este paso se debe realizar cada vez que quieras actualizar el servidor implementado a la versión más reciente.

Implementar en Google Cloud Run

Asegúrate de configurar las variables de entorno necesarias:

  • GOOGLE_PROJECT_IDID del proyecto de Google Cloud, que tiene los niveles de acceso a la API adecuados.
  • GOOGLE_ADS_MCP_OAUTH_CLIENT_ID: Es el ID de cliente de OAuth 2.0 (configurado como una aplicación web en tu proyecto de Google Cloud) para la autenticación de OAuth a nivel de la aplicación. Asegúrate de que ocurra lo siguiente:
    • Agregaste los URIs de redireccionamiento autorizados adecuados para cualquier cliente de IA que planees conectar (como https://claude.ai/api/mcp/auth_callback, https://chatgpt.com/connector_platform_oauth_redirect o https://antigravity.google/oauth-callback).
    • Agregaste el permiso https://www.googleapis.com/auth/adwords a la pantalla de consentimiento de OAuth en APIs y servicios > Pantalla de consentimiento de OAuth > Acceso a los datos (Agregar o quitar permisos).
    • Si el estado de publicación de tu pantalla de consentimiento de OAuth se establece en Prueba (el valor predeterminado), agregaste las Cuentas de Google que se conectan al servidor de MCP como Usuarios de prueba en APIs y servicios > Pantalla de consentimiento de OAuth > Público (Usuarios de prueba > + Agregar usuarios).
  • GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET: Es el secreto del cliente de OAuth que corresponde al ID de cliente de OAuth.
  • GOOGLE_ADS_MCP_BASE_URL: Es la URL base pública en la que se puede acceder a tu servidor de MCP (por ejemplo, https://google-ads-mcp-xyz-uc.a.run.app). Como Google Cloud Run genera esta URL durante la implementación inicial, primero realiza la implementación sin esta variable y, luego, actualiza el servicio después de la implementación.
  • FASTMCP_HOST: Configúralo como 0.0.0.0 para permitir que FastMCP acepte conexiones desde todas las direcciones IP.

Implementa el servicio en Google Cloud Run:

gcloud run deploy google-ads-mcp \
  --image us-central1-docker.pkg.dev/YOUR_PROJECT_ID/mcp-servers/google-ads-mcp:latest \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars="GOOGLE_PROJECT_ID=YOUR_PROJECT_ID,GOOGLE_ADS_MCP_OAUTH_CLIENT_ID=YOUR_CLIENT_ID,GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET=YOUR_CLIENT_SECRET,FASTMCP_HOST=0.0.0.0"

Después de que Cloud Run complete la implementación, recupera la URL del servicio asignada y actualiza el servicio con la variable de entorno GOOGLE_ADS_MCP_BASE_URL:

gcloud run services update google-ads-mcp \
  --region us-central1 \
  --update-env-vars="GOOGLE_ADS_MCP_BASE_URL=https://your-cloud-run-url.a.run.app"

Modelo de autenticación y seguridad

La implementación con --allow-unauthenticated inhabilita la verificación de IAM a nivel de la infraestructura de Cloud Run (roles/run.invoker) para que los clientes de IA externos puedan conectarse sin necesidad de tokens de cuentas de servicio de Google Cloud. En cambio, la autenticación se delega a la capa de aplicación:

  • Cuando se proporcionan GOOGLE_ADS_MCP_OAUTH_CLIENT_ID y GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET, el servidor de MCP aplica Google OAuth 2.0 en todas las solicitudes entrantes, lo que desafía a los emisores no autenticados con una respuesta HTTP 401. Todas las solicitudes de herramientas se ejecutan estrictamente con la identidad de OAuth del emisor autenticado.
  • Omitir --allow-unauthenticated aplica la IAM de la infraestructura de Cloud Run, lo que requiere que los emisores pasen tokens de identidad de OIDC de Google Cloud con cada solicitud. Debido a que los clientes de IA estándar (como Claude y ChatGPT) se autentican con OAuth de usuario final en lugar de tokens de identidad de IAM de Google Cloud, las conexiones directas desde estas plataformas requieren --allow-unauthenticated con OAuth a nivel de la aplicación.

Configura el cliente de MCP

Después de la implementación, configura tu cliente de MCP con la URL de Cloud Run. Debido a que el servidor requiere autenticación de OAuth 2.0, el cliente debe admitir el flujo de OAuth de MCP o proporcionar un token de portador autorizado:

  • Clientes habilitados para OAuth: En el caso de los clientes que admiten el descubrimiento de OAuth de MCP (como Antigravity), la conexión al extremo activa una solicitud de autenticación para acceder con Google y otorgar el permiso https://www.googleapis.com/auth/adwords (que aparece como .../auth/adwords en la consola de Google Cloud).
  • Plataformas de IA de terceros (Claude, ChatGPT): En la configuración de integración o conector de tu cliente, agrega un conector personalizado que apunte a tu URL de Cloud Run con la ruta de acceso /mcp (por ejemplo, https://your-cloud-run-url.a.run.app/mcp), selecciona la autenticación de OAuth 2.0 (con tu propio ID de cliente y secreto de cliente de OAuth) y asegúrate de que el URI de devolución de llamada del cliente se agregue a los URI de redireccionamiento autorizados de tu cliente de OAuth. (Los participantes de la lista de entidades permitidas de la prueba piloto de extremos alojados también pueden consultar la guía de configuración de MCP alojado).
  • Clientes sin compatibilidad con OAuth: Los clientes que no admiten flujos de OAuth de HTTP recibirán una respuesta HTTP 401 No autorizado. Para estas herramientas, usa la configuración de stdio local.

A continuación, se muestra un ejemplo de configuración para un cliente compatible con OAuth (por ejemplo, ~/.gemini/settings.json):

{
  "mcpServers": {
    "google-ads-mcp": {
      "httpUrl": "https://your-cloud-run-url.a.run.app/mcp"
    }
  }
}

Capacidades principales (herramientas)

El servidor expone herramientas diseñadas para el descubrimiento de cuentas y los informes de rendimiento:

  • list_accessible_customers: Devuelve la lista de IDs de cliente de Google Ads y nombres de cuentas a los que puede acceder el usuario autenticado.
  • search: Ejecuta solicitudes de GAQL para recuperar métricas, presupuestos y estados de recursos.

  • get_resource_metadata: Recupera metadatos sobre un tipo de recurso de la API de Google Ads, por ejemplo, "campaign".

    Esto es útil para comprender la estructura de los datos y qué campos están disponibles para realizar consultas.

Instrucciones de ejemplo para comenzar

Pregunta qué puede hacer el servidor:

What can the google-ads-mcp server do?

Pregunta sobre los clientes:

What customers do I have access to?

Pregunta sobre las campañas:

How many active campaigns do I have?
How is my campaign performance this week?
Give me a report of the top spending campaigns split by device category over the
last 7 days for account 1234567890

Próximos pasos