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 plus besoin d'écrire de "code de colle" 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)
  • 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. Consultez la documentation de votre hébergeur pour connaître l'emplacement et le nom exacts de ce fichier de configuration.

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

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. Cette fonctionnalité 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 et transférer l'image 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 cette étape doit être effectuée 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 sera automatiquement attribuée 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 autoriser FastMCP à 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 Google Ads et des noms de compte 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" (campagne).

    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