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 une passerelle standardisée vers l'API Google Ads, qui permet aux agents 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 liaison" personnalisé pour l'authentification, la récupération des ressources et l'analyse des données de l'API Google Ads. 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 diffusable (streamable-http / Cloud Run)
  • Authentification : OAuth 2.0 ou compte de service

Fonctionnement de la boucle d'interaction

  1. Requête : 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 disponibles et identifie les fonctionnalités de recherche de 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 dans 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 de procéder à 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, par exemple settings.json, et faites pointer 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 exact et le nom de fichier de cette 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"
      }
    }
  }
}

Facultatif : Équiper votre agent de compétences et de l'assistant de développement

Le serveur MCP Google Ads donne à votre client IA un accès en lecture seule aux données de compte en temps réel. Pour aider votre agent à créer des requêtes Google Ads Query Language (GAQL) valides, à diagnostiquer les variations de performances du compte et à générer du code de bibliothèque cliente, associez le serveur MCP à ces outils complémentaires :

  • Compétences de l'agent de l'API Google Ads : modules portables d'instructions et de workflows spécifiques à l'API Google Ads, y compris google-ads-api-mcp-setup, google-ads-api-account-diagnostics et google-ads-api-quickstart, qui apprennent à votre agent à utiliser efficacement le serveur MCP Google Ads avec moins de frais généraux de jetons. Installez-les à l'aide d'une seule commande (nécessite Node.js) ou consultez le guide des compétences de l'agent de l'API Google Ads pour les options Antigravity, Claude Code, Codex et Cursor :

    npx skills add google/skills/skills/ads

  • Assistant pour les développeurs de l'API Google Ads : plug-in modulaire pour Google Antigravity et Claude Code qui fournit une inspection locale du schéma Protobuf, une validation GAQL programmatique, une génération de code de bibliothèque cliente (y compris des scripts de mutation) et un dépannage des conversions hors connexion. Pour en savoir plus sur son fonctionnement, consultez Qu'est-ce que l'Assistant du développeur de l'API Google Ads ? ou suivez le guide d'installation.

Déploiement sur Google Cloud

Au lieu d'héberger ce serveur MCP localement, vous pouvez l'héberger sur Google Cloud Run ou sur toute autre infrastructure dans le 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 installé, authentifié et configuré avec un projet actif :

    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 à installer Docker localement.

  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

Veillez à définir les variables d'environnement requises :

  • GOOGLE_PROJECT_ID : ID du projet Google Cloud, qui dispose des niveaux d'accès d'API appropriés.
  • GOOGLE_ADS_MCP_OAUTH_CLIENT_ID : ID client OAuth 2.0 (configuré en tant qu'application Web dans votre projet Google Cloud) pour l'authentification OAuth au niveau de l'application. Vérifiez les points suivants :
    • Vous avez ajouté les URI de redirection autorisés appropriés pour tous les clients d'IA que vous prévoyez de connecter (par exemple, https://claude.ai/api/mcp/auth_callback, https://chatgpt.com/connector_platform_oauth_redirect ou https://antigravity.google/oauth-callback).
    • Vous avez ajouté le champ d'application https://www.googleapis.com/auth/adwords à l'écran de consentement OAuth sous API et services > Écran de consentement OAuth > Accès aux données (Ajouter ou supprimer des champs d'application).
    • Si l'état de publication de votre écran de consentement OAuth est défini sur Test (par défaut), vous avez ajouté les comptes Google se connectant au serveur MCP en tant qu'utilisateurs test sous API et services > Écran de consentement OAuth > Audience (Utilisateurs test > + Ajouter des utilisateurs).
  • GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET : code secret du client OAuth correspondant à l'ID client OAuth.
  • GOOGLE_ADS_MCP_BASE_URL : URL de base publique à laquelle votre serveur MCP est accessible (par exemple, https://google-ads-mcp-xyz-uc.a.run.app). Étant donné que Google Cloud Run génère cette URL lors du déploiement initial, déployez d'abord sans cette variable, puis mettez à jour le service après le déploiement.
  • FASTMCP_HOST : définissez cette option sur 0.0.0.0 pour permettre à FastMCP d'accepter les connexions de toutes les adresses IP.

Déployez le service sur Google Cloud Run :

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,FASTMCP_HOST=0.0.0.0"

Une fois que Cloud Run a terminé le déploiement, récupérez l'URL de service attribuée et mettez à jour le service avec la variable d'environnement GOOGLE_ADS_MCP_BASE_URL :

gcloud run services update google-ads-mcp \
  --region us-central1 \
  --update-env-vars="GOOGLE_ADS_MCP_BASE_URL=https://your-cloud-run-url.a.run.app"

Modèle d'authentification et de sécurité

Le déploiement avec --allow-unauthenticated désactive la vérification IAM au niveau de l'infrastructure de Cloud Run (roles/run.invoker) afin que les clients d'IA externes puissent se connecter sans avoir besoin de jetons de compte de service Google Cloud. L'authentification est déléguée à la couche d'application :

  • Lorsque GOOGLE_ADS_MCP_OAUTH_CLIENT_ID et GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET sont fournis, le serveur MCP applique Google OAuth 2.0 à toutes les requêtes entrantes, en renvoyant une réponse HTTP 401 aux appelants non authentifiés. Toutes les requêtes d'outils s'exécutent strictement sous l'identité OAuth de l'appelant authentifié.
  • L'omission de --allow-unauthenticated applique l'IAM de l'infrastructure Cloud Run, ce qui nécessite que les appelants transmettent des jetons d'identité Google Cloud OIDC à chaque requête. Étant donné que les clients d'IA standards (comme Claude et ChatGPT) s'authentifient à l'aide d'OAuth pour l'utilisateur final plutôt que de jetons d'identité Google Cloud IAM, les connexions directes depuis ces plates-formes nécessitent --allow-unauthenticated avec OAuth au niveau de l'application.

Configurer le client MCP

Après le déploiement, configurez votre client MCP avec l'URL Cloud Run. Comme le serveur nécessite une authentification OAuth 2.0, le client doit prendre en charge le flux OAuth MCP ou fournir un jeton de support autorisé :

  • Clients compatibles avec OAuth : pour les clients compatibles avec la découverte OAuth MCP (comme Antigravity), la connexion au point de terminaison déclenche une invite d'authentification pour se connecter avec Google et accorder le niveau d'accès https://www.googleapis.com/auth/adwords (répertorié comme .../auth/adwords dans la console Google Cloud).
  • Plates-formes d'IA tierces (Claude, ChatGPT) : dans les paramètres du connecteur ou de l'intégration de votre client, ajoutez un connecteur personnalisé pointant vers votre URL Cloud Run avec le chemin d'accès /mcp (par exemple, https://your-cloud-run-url.a.run.app/mcp), sélectionnez l'authentification OAuth 2.0 (en utilisant votre propre ID client et code secret du client OAuth), puis assurez-vous que l'URI de rappel du client est ajouté aux URI de redirection autorisés de votre client OAuth. (Les participants autorisés au pilote de point de terminaison hébergé peuvent également consulter le guide de configuration MCP hébergé.)
  • Clients sans compatibilité OAuth : les clients qui ne sont pas compatibles avec les flux HTTP OAuth recevront une réponse HTTP 401 (Non autorisé). Pour ces outils, utilisez plutôt la configuration stdio locale.

Exemple de configuration pour un client compatible avec OAuth (par exemple, ~/.gemini/settings.json) :

{
  "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 les rapports 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 des requêtes 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 prompts 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

Étapes suivantes