Google Ads MCP Server

This repo contains the source code for running an MCP server that interacts with the Google Ads API.

Herramientas

El servidor utiliza la Google Ads API para proporcionar varias Herramientas y Recursos para su uso con LLMs y agentes de IA.

Herramientas disponibles

• search: Recupera información sobre la cuenta de Google Ads.

• get_resource_metadata: Recupera metadatos sobre un tipo de recurso de la Google Ads API, por ejemplo "campaña". Esto es útil para comprender la estructura de los datos y qué campos están disponibles para consultar.

• list_accessible_customers: Devuelve los IDs de los clientes directamente accesibles por el usuario que autentica la llamada.

Configuración y Espacios de Nombres de Herramientas

El servidor MCP de Google Ads utiliza el tools_config.yaml para permitirle habilitar o deshabilitar selectivamente herramientas individuales o categorías de herramientas (espacios de nombres) y personalizar sus prefijos de espacio de nombres.

Un tools_config.yaml predeterminado con todas las herramientas habilitadas se incluye en el paquete, por lo que el servidor funciona de inmediato sin configuración adicional. Para personalizar su instalación, el servidor resuelve la configuración en el siguiente orden:

1. Una ruta explícita establecida mediante la variable de entorno GOOGLE_ADS_MCP_TOOLS_CONFIG.

2. Un archivo tools_config.yaml en el directorio de trabajo actual.

3. El tools_config.yaml predeterminado incluido en el paquete.

Si falta un archivo de configuración solicitado explícitamente (a través de la variable de entorno) o cualquier archivo resuelto no es válido, el servidor genera un error y no se inicia.

Ejemplo de Configuración:

namespaces:
  # Option 1: Enable category 'customers' with default prefix -> "customers_list_accessible_customers"
  customers: true

  # Option 2: Enable category 'search' with a custom prefix -> "query_search"
  search: "query"

  # Option 3: Fine-grained control over tools in a category
  metadata:
    enabled: true
    prefix: "metadata"
    enabled_tools:
      - get_resource_metadata: true

Recursos disponibles

• discovery-document: Recupera el documento de descubrimiento de la Google Ads API. Proporciona el documento de descubrimiento para la última versión de la Google Ads API, que describe la superficie de la API, incluidos recursos, métodos y esquemas. Los LLM anfitriones deben acceder a este recurso para comprender la estructura de la Google Ads API y descubrir las funciones disponibles.

• metrics: Recupera información sobre las métricas disponibles para la generación de informes en la Google Ads API.

• segments: Recupera información sobre los segmentos disponibles para la generación de informes en la Google Ads API.

• release-notes: Recupera las notas de la versión de la última versión de la Google Ads API.

Related MCP server: gads

Notas

1. El servidor MCP expondrá sus datos al Agente o LLM al que se conecte.

2. Si tiene problemas técnicos, utilice el rastreador de incidencias de GitHub.

3. Para ayudarnos a recopilar datos de uso, notará que se ha añadido un encabezado adicional a sus llamadas a la API: estos datos se utilizan para mejorar el producto.

Instrucciones de configuración

La configuración implica los siguientes pasos:

1. Configurar Python.

2. Configurar el token de desarrollador.

3. Habilitar las API en su proyecto.

4. Configurar las credenciales.

5. Configurar su cliente MCP.

Configurar Python

Instale pipx.

Configurar el token de desarrollador

Siga las instrucciones para Obtener un token de desarrollador.

Su token de desarrollador debe tener al menos acceso de Explorador para consultar cuentas de producción. Los tokens nuevos pueden actualizarse automáticamente al acceso de Explorador; si no, puede solicitarlo a través del Centro de API. Consulte la documentación de niveles de acceso para obtener más detalles.

Si ve el error "El token de desarrollador solo está aprobado para su uso con cuentas de prueba", su token aún no tiene acceso a cuentas de producción. Consulte la documentación de niveles de acceso para saber cómo solicitar el nivel de acceso que necesita.

Habilitar las API en su proyecto

Siga las instrucciones para habilitar las siguientes API en su proyecto de Google Cloud:

• Google Ads API

Configurar las credenciales

Opción 1: Usar el proxy OAuth de FastMCP

El servidor admite la función de proxy OAuth de FastMCP para la autenticación dinámica de usuarios. Esto es útil cuando se ejecuta el servidor como un servicio web.

Para habilitarlo, configure las siguientes variables de entorno:

• GOOGLE_ADS_MCP_OAUTH_CLIENT_ID: Su ID de cliente OAuth 2.0 de Google Cloud.

• GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET: Su secreto de cliente OAuth 2.0 de Google Cloud.

• GOOGLE_ADS_MCP_BASE_URL: (Opcional) La URL base donde el servidor es accesible (por defecto http://localhost:8080).

• GOOGLE_ADS_MCP_JWT_SIGNING_KEY: (Opcional) Clave secreta utilizada para firmar tokens JWT de FastMCP en múltiples instancias o implementaciones de servidores.

• GOOGLE_ADS_MCP_STORAGE_TYPE: (Opcional) Backend de almacenamiento para el estado OAuth (filetree, redis, firestore o memory).

• GOOGLE_ADS_MCP_STORAGE_PATH: (Opcional) Ruta de directorio para el almacenamiento persistente filetree.

• GOOGLE_ADS_MCP_STORAGE_REDIS_URL: (Opcional) URL de Redis para el almacenamiento persistente redis.

• GOOGLE_ADS_MCP_STORAGE_FIRESTORE_PROJECT: (Opcional) Proyecto de Google Cloud para el almacenamiento persistente firestore. Por defecto, se infiere del proyecto de las Credenciales predeterminadas de la aplicación. Establecerlo selecciona el backend firestore incluso si GOOGLE_ADS_MCP_STORAGE_TYPE no está configurado.

• GOOGLE_ADS_MCP_STORAGE_FIRESTORE_DATABASE: (Opcional) Nombre de la base de datos Firestore para el almacenamiento persistente firestore. Por defecto es (default).

• GOOGLE_ADS_MCP_STORAGE_ENCRYPTION_KEY: (Opcional) Clave de cifrado para los tokens OAuth almacenados.

• GOOGLE_ADS_MCP_STORAGE_DISABLE_ENCRYPTION: (Opcional) Establézcalo en true para deshabilitar el cifrado de tokens.

Los backends redis y firestore necesitan que su biblioteca de almacenamiento esté instalada junto con el servidor: pip install py-key-value-aio[redis] y pip install google-ads-mcp[firestore] respectivamente.

Una vez habilitado, puede autenticarse en la API a través de su cliente MCP.

Cuando se configuran estas variables, el servidor cambia automáticamente al transporte streamable-http (SSE/HTTP) en lugar de stdio.

Deberá ejecutar el servidor como un proceso separado y configurar su cliente MCP para conectarse al endpoint SSE (por ejemplo, http://localhost:8080/mcp).

Opción 2: Configurar las credenciales con las Application Default Credentials

Configure sus Application Default Credentials (ADC). Asegúrese de que las credenciales correspondan a un usuario con acceso a sus cuentas o propiedades de Google Ads.

Las credenciales deben incluir el alcance de la Google Ads API:

https://www.googleapis.com/auth/adwords

Consulte Manage OAuth Clients para saber cómo crear un cliente OAuth.

Aquí hay algunos comandos de gcloud de ejemplo que pueden resultarle útiles:

• Configure ADC con credenciales de usuario y un cliente OAuth de escritorio o web después de descargar el JSON del cliente en YOUR_CLIENT_JSON_FILE.

  gcloud auth application-default login \
    --scopes https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform \
    --client-id-file=YOUR_CLIENT_JSON_FILE

• Configure ADC mediante la suplantación de una cuenta de servicio.

  gcloud auth application-default login \
    --impersonate-service-account=SERVICE_ACCOUNT_EMAIL \
    --scopes=https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform

Cuando el comando gcloud auth application-default se complete, copie la ubicación del archivo PATH_TO_CREDENTIALS_JSON que se imprime en la consola en el siguiente mensaje. ¡Necesitará esto para un paso posterior!

Credentials saved to file: [PATH_TO_CREDENTIALS_JSON]

Opción 3: Configurar las credenciales con la biblioteca cliente de Python de la Google Ads API

Siga las instrucciones para configurar la biblioteca cliente de Python de la Google Ads API.

Si ya ha hecho esto y tiene un archivo google-ads.yaml funcional, ¡puede reutilizar este archivo!

En el archivo utils.py, cambie get_googleads_client() para que use el método load_from_storage().

Configurar su cliente MCP

Agregue el servidor a la configuración de su cliente MCP. A continuación se muestran ejemplos para clientes populares.

Antigravity CLI / Antigravity Code Assist

1. Instale Antigravity CLI o Antigravity Code Assist.

2. Configure su servidor. Consulte la documentación en https://antigravity.google/docs/mcp para obtener detalles sobre cómo configurar servidores MCP.

• Opción 1: Usar el proxy OAuth de FastMCP (Streamable HTTP)

  Puede ejecutar el servidor como un proceso separado y configurar su cliente MCP para conectarse al endpoint SSE (por ejemplo, http://localhost:8080/mcp). Esto también permite usar la función de proxy OAuth de FastMCP para la autenticación dinámica de usuarios.

  {
    "mcpServers": {
      "google-ads-mcp": {
        "httpUrl":"http://localhost:8080/mcp",
        "env": {
          "GOOGLE_PROJECT_ID": "YOUR_PROJECT_ID",
          "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN"                        
        }
      }
    }
  }

• Opción 2: el método de Application Default Credentials

  Reemplace PATH_TO_CREDENTIALS_JSON con la ruta que copió en el paso anterior.

  También recomendamos que agregue un atributo GOOGLE_CLOUD_PROJECT al objeto env. Reemplace YOUR_PROJECT_ID en el siguiente ejemplo con el ID del proyecto de su proyecto de Google Cloud.

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

• Opción 3: el método de la biblioteca cliente de Python

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

Login Customer Id

Si su acceso a la cuenta de cliente es a través de una cuenta de administrador, deberá agregar el ID de cliente de la cuenta de administrador al archivo de configuración.

Consulte aquí para obtener más detalles.

El archivo final se verá así:

{
  "mcpServers": {
    "google-ads-mcp": {
      "command": "pipx",
      "args": [
        "run",
        "--spec",
        "git+https://github.com/googleads/google-ads-mcp.git",
        "google-ads-mcp"
      ],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON",
        "GOOGLE_PROJECT_ID": "YOUR_PROJECT_ID",
        "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "YOUR_MANAGER_CUSTOMER_ID"
      }
    }
  }
}

Otros clientes MCP (Claude Code, Cursor, VS Code, etc.)

El formato del bloque mcpServers es el mismo en todos los clientes MCP. Agregue la configuración que se muestra arriba al archivo de configuración correspondiente para su cliente (por ejemplo, ~/.claude/settings.json para Claude Code, .cursor/mcp.json para Cursor, .vscode/mcp.json para VS Code con Copilot).

Implementación en Google Cloud Platform

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

Tenga en cuenta que esto solo admite la autenticación con un par de ID de cliente OAuth y secreto de cliente a través del proxy OAuth (Opción #1 anterior).

Requisitos previos

1. Un proyecto de Google Cloud.

2. La CLI de gcloud instalada, autenticada y con el proyecto activo configurado.

gcloud config set project YOUR_PROJECT_ID

Paso 1: Crear y enviar la imagen de Docker

Puede usar Cloud Build para crear y enviar la imagen a Artifact Registry sin necesidad de tener Docker instalado localmente.

1. Cree un repositorio en Artifact Registry:

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

2. Cree y envíe la imagen:

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

Reemplace YOUR_PROJECT_ID con el ID de su proyecto de Google Cloud.

Paso 2: Implementar en Google Cloud Run

Asegúrese de configurar las variables de entorno necesarias:

• GOOGLE_PROJECT_ID: El ID de tu proyecto de Google Cloud.

• GOOGLE_ADS_DEVELOPER_TOKEN: El token de desarrollador que quieres que use el servidor MCP (ver más arriba).

• GOOGLE_ADS_MCP_OAUTH_CLIENT_ID: El ID de cliente OAuth que quieres que use el servidor MCP.

• GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET: El secreto de cliente OAuth que quieres que use el servidor MCP.

• GOOGLE_ADS_MCP_BASE_URL: La URL base donde tu servidor MCP es accesible: será asignada automáticamente por Google Cloud Run después de tu primer despliegue. Puedes actualizar las variables de entorno después del despliegue.

• GOOGLE_ADS_MCP_JWT_SIGNING_KEY: (Recomendado para producción) Clave de firma JWT persistente entre instancias de Cloud Run.

• GOOGLE_ADS_MCP_STORAGE_TYPE: (Recomendado para producción) Backend de almacenamiento para persistir tokens OAuth entre instancias. Establézcalo en firestore para usar Firestore a través de las Credenciales de Aplicación Predeterminadas, lo que no necesita un conector VPC, o en redis junto con GOOGLE_ADS_MCP_STORAGE_REDIS_URL.

  Usar firestore requiere tres cosas: construir la imagen con el extra instalado (cambiar el Dockerfile a uv pip install --system .[firestore]), crear una base de datos Firestore en el proyecto, ya que no se aprovisiona una automáticamente, y otorgar a la cuenta de servicio de Cloud Run el rol roles/datastore.user. Tenga en cuenta que las entradas no caducan automáticamente: el almacén filtra las entradas caducadas al leer pero nunca las elimina, y expires_at se escribe como una cadena, por lo que una política TTL de Firestore tampoco puede recogerlas. Planifique un trabajo de limpieza periódica para despliegues de larga duración. Redis caduca las entradas por sí mismo.

• FASTMCP_HOST: Establezca esto 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,GOOGLE_ADS_MCP_JWT_SIGNING_KEY=YOUR_JWT_SIGNING_KEY,GOOGLE_ADS_MCP_STORAGE_TYPE=firestore,FASTMCP_HOST=0.0.0.0"

Paso 3: Configurar el Cliente MCP

Una vez desplegado, actualice la configuración de su cliente MCP (consulte la documentación en https://antigravity.google/docs/mcp) para usar la URL de Cloud Run.

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

Pruébelo

Inicie su cliente MCP. Debería ver google-ads-mcp listado en los servidores disponibles.

Aquí hay algunos ejemplos de indicaciones para empezar:

• Pregunte qué puede hacer el servidor:

  what can the ads-mcp server do?

• Pregunte sobre clientes:

  what customers do I have access to?

• Pregunte sobre campañas

  How many active campaigns do I have?

  How is my campaign performance this week?

Nota sobre el ID de Cliente

Su agente necesitará y solicitará un ID de cliente para la mayoría de las indicaciones. Si se está moviendo entre múltiples clientes, incluir el ID de cliente en la indicación puede ser más simple.

How many active campaigns do I have for customer id 1234567890

Contribuir

¡Las contribuciones son bienvenidas! Consulte la Guía de Contribución.