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)
  • 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 consola para desarrolladores de Google Ads:

  • Token de desarrollador: Es tu cadena de acceso única de 22 caracteres.
  • ID del proyecto: Es el identificador de tu proyecto de Google Cloud.
  • Credenciales de OAuth: Un par de ID de cliente y secreto de cliente de OAuth2, 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 del host, como settings.json. Consulta la documentación del 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",
        "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN"
      }
    }
  }
}

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. 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.
  • GOOGLE_ADS_DEVELOPER_TOKEN: Es el token de desarrollador que deseas que use el servidor de MCP.
  • 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 de 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 en 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_DEVELOPER_TOKEN=YOUR_DEVELOPER_TOKEN,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 de tu 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 IDs de cliente y nombres de cuenta 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, presupuestos y estados de recursos.

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

    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