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 des données de campagne en langage naturel.

Ressources de la communauté et assistance

  • Dépôt GitHub : retrouvez des démonstrations et des exemples, signalez des bugs ou suggérez des fonctionnalités dans le dépôt google-ads-mcp.

    Utilisez l'onglet Issues (Problèmes) pour signaler des bugs et formuler des demandes de fonctionnalités.

  • Communauté : rejoignez le canal #ads-api-ai-tools sur le Discord de la communauté Google Advertising.

Présentation technique

En implémentant ce serveur MCP, vous n'avez plus besoin d'écrire de "code de liaison" personnalisé pour l'authentification de l'API Google Ads, la récupération de ressources et l'analyse de 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)
  • Langue : 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 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 de procéder à la configuration, assurez-vous de disposer des identifiants suivants dans la Google Cloud console :

  • ID du projet : ID de votre projet Google Cloud (GOOGLE_PROJECT_ID). Consultez la page de présentation de l'API Google Ads pour vous assurer que votre projet dispose des niveaux d'accès Explorateur, Basique ou Standard. Si ce n'est pas le cas, demandez l'un de ces niveaux d'accès. Notez que les jetons de développeur (GOOGLE_ADS_DEVELOPER_TOKEN) ont été abandonnés le 9 septembre 2026 et ne sont plus requis dans la dernière version du serveur MCP Google Ads, car les niveaux d'accès à l'API sont associés au projet Google Cloud.
  • Identifiants OAuth : paire d'ID client/code secret du client OAuth 2.0 ou ensemble d'identifiants par défaut de l'application.

Configuration

Pour intégrer le serveur dans 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 à des comptes via un compte administrateur, vous pouvez également définir GOOGLE_ADS_LOGIN_CUSTOMER_ID. Consultez la documentation de votre hôte 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"
      }
    }
  }
}

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 avec un projet actif 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 à 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

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 2.0 (configuré en tant qu'application Web dans votre projet Google Cloud) pour l'authentification OAuth au niveau de l'application. Assurez-vous que :
    • 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 où 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-la d'abord sans cette variable, puis mettez à jour le service 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.

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 le déploiement terminé dans Cloud Run, 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), de sorte que les clients d'IA externes peuvent se connecter sans avoir besoin de jetons de compte de service Google Cloud. L'authentification est plutôt déléguée à la couche 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 défiant les appelants non authentifiés avec une réponse HTTP 401. 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 oblige les appelants à transmettre des jetons d'identité OIDC Google Cloud à chaque requête. Étant donné que les clients d'IA standards (tels que Claude et ChatGPT) s'authentifient à l'aide d'OAuth de l'utilisateur final plutôt que de jetons d'identité Google Cloud IAM, les connexions directes à partir de 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. Étant donné que le serveur nécessite l'authentification OAuth 2.0, le client doit être compatible avec le flux OAuth MCP ou fournir un jeton porteur autorisé :

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

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 la création de rapports sur les performances :

  • list_accessible_customers: renvoie la liste des ID client Google Ads et des noms de compte accessibles à l'utilisateur authentifié.
  • search: exécute des 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 est utile pour 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?

Posez 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