Serveur MCP Google Ads : guide d'intégration pour les développeurs

Le Model Context Protocol (MCP) est une norme ouverte qui permet aux grands modèles de langage (LLM) d'interagir de manière sécurisée avec des données et des applications externes. Le serveur MCP Google Ads fournit un pont standardisé vers l'API Google Ads, qui permet aux agents d'IA d'analyser et de récupérer les données de campagne en langage naturel.

Ressources et assistance de la communauté

Présentation technique

En implémentant ce serveur MCP, vous n'avez pas besoin d'écrire de "code de liaison" personnalisé pour l'authentification de l'API Google Ads, la récupération des ressources et l'analyse des données. Le serveur expose des outils spécifiques qu'un LLM peut découvrir et appeler de manière autonome.

Caractéristiques techniques

  • Protocole : MCP (Model Context Protocol)
  • Mode : Lecture seule (version actuelle)
  • Langage : Python
  • Transport : entrée/sortie standard (stdio) ou HTTP/SSE (Cloud Run)
  • Authentification : OAuth 2.0 ou compte de service

Fonctionnement de la boucle d'interaction

  1. Demande : un utilisateur envoie une requête telle que "Quelles sont les performances de ma campagne cette semaine ?".
  2. Découverte : le LLM inspecte les outils à sa disposition et identifie les fonctionnalités de recherche google-ads-mcp.
  3. Exécution : le serveur MCP exécute la logique Python sous-jacente pour interroger l'API Google Ads.
  4. Injection de contexte : les résultats structurés sont renvoyés à la fenêtre de contexte du LLM.
  5. Réponse : le LLM synthétise les données dans une réponse lisible par l'humain.

Commencer

Suivez ces étapes pour configurer et utiliser le serveur MCP Google Ads.

Prérequis

Avant la configuration, assurez-vous de disposer des identifiants suivants dans la console Google Cloud :

Configuration

Pour intégrer le serveur à un hôte compatible avec MCP, ajoutez l'entrée suivante au fichier de configuration MCP de votre hôte, tel que settings.json, et pointez GOOGLE_APPLICATION_CREDENTIALS vers votre fichier JSON ADC (ou configurez l'ADC par défaut avec gcloud auth application-default login). Si vous accédez aux comptes via un compte administrateur, vous pouvez également définir GOOGLE_ADS_LOGIN_CUSTOMER_ID. Consultez la documentation de votre hébergeur pour connaître l'emplacement et le nom exacts de ce fichier de configuration.

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

Déploiement sur Google Cloud

Au lieu d'héberger ce serveur MCP en local, vous pouvez l'héberger sur Google Cloud Run ou sur toute autre infrastructure cloud. Cela est utile si vous souhaitez partager le serveur entre différents agents ou l'exécuter en tant que service Web.

Prérequis

  1. Un projet Google Cloud.

  2. L'outil de ligne de commande gcloud est installé, authentifié et un projet actif est configuré :

    gcloud config set project YOUR_PROJECT_ID

Créer et transférer une image Docker

Vous pouvez utiliser Cloud Build pour créer l'image et la transférer vers Artifact Registry sans avoir besoin d'installer Docker en local.

  1. Créez un dépôt dans Artifact Registry :

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

  2. Accédez au répertoire du projet :

    cd <full path>/google-ads-mcp

  3. Créez et envoyez l'image :

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

    Notez que vous devez effectuer cette étape chaque fois que vous souhaitez mettre à jour le serveur déployé vers la dernière version.

Déployer sur Google Cloud Run

Assurez-vous de définir les variables d'environnement requises :

  • GOOGLE_PROJECT_ID : ID de votre projet Google Cloud, qui dispose des niveaux d'accès à l'API appropriés.
  • GOOGLE_ADS_MCP_OAUTH_CLIENT_ID : ID client OAuth que vous souhaitez que le serveur MCP utilise.
  • GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET : code secret du client OAuth que vous souhaitez que le serveur MCP utilise.
  • GOOGLE_ADS_MCP_BASE_URL : URL de base à laquelle votre serveur MCP est accessible. Elle est attribuée automatiquement par Google Cloud Run après votre premier déploiement. Vous pouvez mettre à jour les variables d'environnement après le déploiement.
  • FASTMCP_HOST : définissez cette valeur sur 0.0.0.0 pour permettre à FastMCP d'accepter les connexions de toutes les adresses 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"

Configurer le client MCP

Après le déploiement, mettez à jour la configuration de votre client MCP (par exemple, ~/.gemini/settings.json) pour utiliser l'URL Cloud Run.

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

Fonctionnalités de base (outils)

Le serveur expose des outils conçus pour la découverte de comptes et le reporting sur les performances :

  • list_accessible_customers : renvoie la liste des numéros client et des noms de compte Google Ads accessibles à l'utilisateur authentifié.
  • search : exécute les requêtes Google Ads Query Language (GAQL) pour récupérer les métriques, les budgets et l'état des ressources.

  • get_resource_metadata : récupère les métadonnées d'un type de ressource de l'API Google Ads, par exemple "campaign".

    Cela permet de comprendre la structure des données et les champs disponibles pour les requêtes.

Exemples de requêtes pour commencer

Demandez ce que le serveur peut faire :

What can the google-ads-mcp server do?

Posez des questions sur les clients :

What customers do I have access to?

Poser des questions sur les campagnes :

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