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 para la comunidad

Descripción técnica general

Si implementas este servidor de MCP, ya no tendrás que escribir "código de pegamento" 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/salida estándar (stdio)
  • Autenticación: OAuth 2.0 o cuenta de servicio

Cómo funciona el bucle de interacción

  1. Solicitud: Un usuario envía una búsqueda como "¿Cómo es el rendimiento de mi campaña esta semana?".
  2. Descubrimiento: El LLM inspecciona las herramientas disponibles y reconoce 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. Inyecció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:

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. Consulta la documentación de tu host para conocer la ubicación y el nombre de archivo exactos de esta configuración.

JSON

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

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 desees actualizar el servidor implementado a la versión más reciente.

Implementa 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 que deseas que use el servidor de MCP.
  • GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET: Es el secreto del cliente de OAuth que deseas que use el servidor de MCP.
  • GOOGLE_ADS_MCP_BASE_URL: Es la URL base en la que se puede acceder a tu servidor de MCP. Google Cloud Run la asignará automáticamente después de tu primera implementación. Puedes actualizar las variables de entorno después de la implementación.
  • FASTMCP_HOST: Configúralo como 0.0.0.0 para permitir que FastMCP acepte conexiones de todas las direcciones IP.
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,GOOGLE_ADS_MCP_BASE_URL=YOUR_BASE_URL,FASTMCP_HOST=0.0.0.0"

Configura el cliente de MCP

Después de la implementación, actualiza la configuración del cliente de MCP (por ejemplo, ~/.gemini/settings.json) para usar la URL de Cloud Run.

{
  "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 los IDs de cliente y los nombres de las cuentas de Google Ads a los que puede acceder el usuario autenticado.
  • search: Ejecuta solicitudes del lenguaje de consultas de Google Ads (GAQL) para recuperar métricas de recursos, presupuestos y estados.

  • 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 las consultas.

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