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, 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, no tendrás que 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)
  • Idioma: Python
  • Transporte: Entrada/salida estándar (stdio) o HTTP transmisible (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 las 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 subyacente de Python para consultar la API de Google Ads.
  4. Inyección de contexto: Los resultados estructurados se muestran en 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 Google Cloud console:

Configuración

Para integrar el servidor en un host compatible con MCP, agrega la siguiente entrada al archivo de configuración de MCP del host, como settings.json, y haz que GOOGLE_APPLICATION_CREDENTIALS apunte a tu archivo JSON de ADC (o configura el ADC predeterminado con gcloud auth application-default login). Si accedes a las cuentas a través de una cuenta de administrador, también puedes establecer GOOGLE_ADS_LOGIN_CUSTOMER_ID. Consulta la documentación de tu host para conocer la ubicación y el nombre de archivo exactos 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"
      }
    }
  }
}

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

Crea y envía una imagen de Docker

Puedes usar Cloud Build para compilar y enviar la imagen a Artifact Registry sin necesidad de tener Docker instalado 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 desees 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_ID: Es el ID 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 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 alcance https://www.googleapis.com/auth/adwords a la pantalla de consentimiento de OAuth en APIs y servicios > Pantalla de consentimiento de OAuth > Acceso a datos (Agregar o quitar alcances).
    • Si el estado de publicación de la pantalla de consentimiento de OAuth está establecido 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). Debido a que Google Cloud Run genera esta URL durante la implementación inicial, primero implementa sin esta variable y, luego, actualiza el servicio después de la implementación.
  • FASTMCP_HOST: Establece este valor en 0.0.0.0 para permitir que FastMCP acepte conexiones de 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 de 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 y desafía a los llamadores no autenticados con una respuesta HTTP 401. Todas las solicitudes de herramientas se ejecutan estrictamente bajo la identidad de OAuth del llamador autenticado.
  • Si se omite --allow-unauthenticated, se aplica IAM de la infraestructura de Cloud Run, lo que requiere que los llamadores 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 alcance 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 del conector o la integración 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 URIs de redireccionamiento autorizados de tu cliente de OAuth. (Los participantes incluidos en la lista de entidades permitidas de la versión piloto del extremo alojado también pueden consultar la guía de configuración de MCP alojada).
  • 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 en su lugar.

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 la generación de informes de rendimiento:

  • list_accessible_customers: Muestra la lista de IDs de cliente de Google Ads y nombres de cuenta a los que puede acceder el usuario autenticado.
  • search: Ejecuta solicitudes del lenguaje de consultas de Google Ads (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 la consulta.

Ejemplos de instrucciones 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