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, ce qui permet aux agents d'IA d'analyser et de récupérer des 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 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)
  • 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 "Comment mes campagnes ont-elles performé 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.

Premiers pas

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 Google Ads Developer Console :

  • Jeton de développeur : chaîne d'accès unique de 22 caractères.
  • ID du projet : identifiant de votre projet Google Cloud.
  • Identifiants OAuth : paire d'ID client/code secret du client OAuth2 ou ensemble d'identifiants par défaut de l'application.

Configuration

Pour intégrer le serveur dans un hôte compatible avec le protocole MCP, ajoutez l'entrée suivante au fichier de configuration MCP de votre hôte, par exemple settings.json. Consultez la documentation de votre hôte pour connaître l'emplacement exact et le nom de fichier de cette 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",
        "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN"
      }
    }
  }
}

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 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. 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.
  • GOOGLE_ADS_DEVELOPER_TOKEN : jeton de développeur que vous souhaitez que le serveur MCP utilise.
  • 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 où 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_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,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 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 en langage de requête Google Ads (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 "campagne".

    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