Serveur Google Ads MCP 🚀

Un serveur de protocole de contexte de modèle alimenté par FastMCP pour l'intégration de l'API Google Ads avec authentification automatique OAuth 2.0

Connectez l'API Google Ads directement à Claude Desktop et à d'autres clients MCP avec une authentification OAuth 2.0 transparente, un rafraîchissement automatique des jetons, une interrogation GAQL et des capacités de recherche de mots clés.

Votre navigateur ne supporte pas la balise vidéo.

Installation facile en un clic

Pour une expérience de configuration plus simple, nous proposons des installateurs prêts à l'emploi :

👉 Télécharger le programme d'installation -https://gomarble.ai/mcp

Rejoignez notre communauté pour obtenir de l'aide et des mises à jour

👉 Communauté Slack -AI in Ads

Essayez Facebook ads mcp server aussi

👉 Facebook Ads MCP -Facebook Ads MCP

✨ Features

• 🔐 O Auth 2.0 automatique - Authentification unique du navigateur avec rafraîchissement automatique
• 🔄 Gestion intelligente des jetons - Gestion automatique des jetons expirés
• 📊 Exécution des requêtes GAQL - Exécution de toutes les requêtes Google Ads Query Language
• 🏢 Gestion des comptes - Liste et gestion des comptes Google Ads
• 🔍 Recherche de mots clés - Générer des idées de mots clés avec des données de volume de recherche
• fastMCP Framework - Construit sur le standard moderne MCP
• 🖥️ Claude Desktop Ready - Intégration directe avec Claude Desktop
• 🛡️ Secure Local Storage - Tokens stockés localement, jamais exposés

📋 Outils disponibles

Remarque : tous les outils gèrent automatiquement l'authentification - aucun paramètre de jeton n'est requis !

🚀 Démarrage rapide

Conditions préalables

Avant de configurer le serveur MCP, vous aurez besoin de :

• Python 3.10+ installé
• Un compte Google Cloud Platform
• Un compte Google Ads avec accès à l'API

🔧 Étape 1 : Configuration de Google Cloud Platform

1.1 Créer un projet Google Cloud

1. Aller dans la console Google Cloud
2. Créez un nouveau projet
   • Cliquer sur "Sélectionner un projet" → "Nouveau projet"
   • Saisir le nom du projet (par exemple, "Google Ads MCP")
   • Cliquez sur "Créer"

1.2 Activer l'API Google Ads

1. Dans votre Google Cloud Console
   • Allez dans "APIs & Services" → "Library"
   • Recherchez "Google Ads API"
   • Cliquez dessus et appuyez sur "Activer"

1.3 Créer les informations d'identification OAuth 2.0

1. Allez dans "APIs & Services" → "Credentials"
2. Cliquez sur "+ CREATE CREDENTIALS" → "OAuth 2.0 Client ID"
3. Configurer l'écran de consentement (si c'est la première fois)
   • Cliquez sur "Configurer l'écran de consentement"
   • Choisissez "Externe" (sauf si vous avez Google Workspace)
   • Remplissez les champs obligatoires
     • Nom de l'application : "Google Ads MCP"
     • Adresse électronique de l'assistance utilisateur : Votre adresse e-mail
     • Contact développeur : Votre email
   • Cliquez sur "Enregistrer et continuer" à toutes les étapes
4. Créer un client OAuth
   • Type d'application : "Application de bureau"
   • Nom : "Client MCP Google Ads"
   • Cliquez sur "Créer"
5. Télécharger les informations d'identification
   • Cliquez sur le bouton "Télécharger JSON
   • Enregistrez le fichier sous le nom client_secret_[chaîne longue].json dans le répertoire de votre projet

🔧 Étape 2 : Configuration de l'API Google Ads

2.1 Obtenir le jeton de développeur

1. Connectez-vous à Google Ads
2. Accédez à Outils et paramètres (icône de clé à molette dans la barre de navigation supérieure)
3. Sous "Configuration", cliquez sur "Centre API"
4. Acceptez les conditions d'utilisation si vous y êtes invité
5. Cliquez sur "Apply for token" (demander un jeton)
6. Remplissez le formulaire de demande
   • Décrivez votre cas d'utilisation (par exemple, "Intégration MCP pour l'analyse des campagnes")
   • Fournissez des détails techniques sur votre mise en œuvre
7. Soumettez votre demande et attendez l'approbation (généralement 1 à 3 jours ouvrables)

Remarque : vous recevrez dans un premier temps un jeton de test aux fonctionnalités limitées. Une fois le test terminé, vous pouvez demander l'accès à la version de production.

2.2 Trouvez votre jeton de développeur

Une fois votre demande approuvée :

1. Retournez au Centre API dans Google Ads
2. Copiez votre jeton de développeur (format : XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX)

🔧 Étape 3 : Installation et configuration

3.1 Cloner et installer

# Cloner le dépôt git clone https://github.com/yourusername/google-ads-mcp-server.git cd google-ads-mcp-server # Créer un environnement virtuel (recommandé) python3 -m venv .venv source .venv/bin/activate # Sous Windows : .venv\Scripts\activate # Installer les dépendances pip install -r requirements.txt

3.2 Configuration de l'environnement

Créez un fichier .env dans le répertoire de votre projet :

# Copier le fichier exemple cp .env.example .env

Editez le fichier . env avec vos identifiants :

# Requis : Token du développeur de l'API Google Ads GOOGLE_ADS_DEVELOPER_TOKEN=votre_token_developpeur_ici # Requis : Chemin d'accès au fichier JSON des informations d'identification OAuth (téléchargé depuis Google Cloud) GOOGLE_ADS_OAUTH_CONFIG_PATH=/full/path/to/your/client_secret_file.json

Exemple de fichier .env :

GOOGLE_ADS_DEVELOPER_TOKEN=ABCDEFG1234567890 GOOGLE_ADS_OAUTH_CONFIG_PATH=/Users/john/google-ads-mcp/client_secret_138737274875-abc123.apps.googleusercontent.com.json

🖥️ Étape 4 : Intégration du bureau de Claude

4.1 Localiser la configuration de Claude

Trouvez votre fichier de configuration de Claude Desktop :

macOS :

~/Bibliothèque/Application Support/Claude/claude_desktop_config.json

Windows :

%APPDATA%\Claude\claude_desktop_config.json

4.2 Ajouter la configuration du serveur MCP

Modifiez le fichier de configuration et ajoutez votre serveur Google Ads MCP :

{ "mcpServers" : {"google-ads" : { "command" : "/full/path/to/your/project/.venv/bin/python", "args" : ["/full/path/to/your/project/server.py" ] } } }

Exemple réel :

{ "mcpServers" : { "google-ads" : { "command" : "/Users/marble-dev-01/workspace/google_ads_with_fastmcp/.venv/bin/python", "args" : ["/Users/marble-dev-01/workspace/google_ads_with_fastmcp/server.py" ] } } }

Important :

• Utilisez des chemins absolus pour tous les emplacements de fichiers
• Sous Windows, utilisez les barres obliques avant / ou les doubles barres obliques arrière \\N dans les chemins d'accès
• Remplacer your_developer_token_here par votre token de développeur actuel

4.3 Redémarrer Claude Desktop

Fermer et redémarrer Claude Desktop pour charger la nouvelle configuration.

🔐 Etape 5 : Première authentification

5.1 Déclencher le flux OAuth

1. Ouvrez Claude Desktop
2. Essayez n'importe quelle commande Google Ads, par exemple :

   "List all my Google Ads accounts" (Liste de tous mes comptes Google Ads)

5.2 Compléter l'authentification

1. Lenavigateur s'ouvre automatiquement sur la page OAuth de Google
2. Connectez-vous avec votre compte Google (celui qui a accès à Google Ads)
3. Accordez les autorisations en cliquant sur "Autoriser"
4. Le navigateur affiche la page de succès
5. Retournez à Claude - votre commande se terminera automatiquement !

5.3 Vérifier la configuration

Après l'authentification, vous devriez voir

• Un fichier google_ads_token.json créé dans le répertoire de votre projet
• Vos comptes Google Ads listés dans la réponse de Claude

exemples d'utilisation

Opérations de base sur les comptes

"List all my Google Ads accounts" "Show me the account details and which ones have active campaigns" (Liste de tous mes comptes Google Ads)

Analyse des campagnes

"Show me campaign performance for account 1234567890 in the last 30 days" "Get conversion data for all campaigns in the last week" "Which campaigns have the highest cost per conversion ?"

Recherche de mots-clés

"Générer des idées de mots-clés pour 'digital marketing' en utilisant le compte 1234567890" "Trouver des opportunités de mots-clés pour 'AI automation' avec des données de volume de recherche" "Rechercher des mots-clés pour la page https://example.com/services"

Requêtes GAQL personnalisées

"Exécuter cette requête GAQL pour le compte 1234567890 : SELECT campaign.name, metrics.clicks, metrics.cost_micros FROM campaign WHERE segments.date DURING LAST_7_DAYS" "Obtenir des données sur les performances des mots-clés : SELECT ad_group_criterion.keyword.text, metrics.ctr, metrics.average_cpc FROM keyword_view WHERE metrics.impressions > 100"

🔍 Exemples avancés de GAQL

Performance d'une campagne avec revenus

SELECT campaign.id, campaign.name, metrics.clicks, metrics.impressions, metrics.cost_micros, metrics.conversions, metrics.conversions_value FROM campaign WHERE segments.date DURING LAST_30_DAYS ORDER BY metrics.cost_micros DESC

Analyse de la performance des mots-clés

SELECT campaign.name, ad_group_criterion.keyword.text, ad_group_criterion.keyword.match_type, metrics.ctr, metrics.average_cpc, metrics.quality_score FROM keyword_view WHERE segments.date DURING LAST_7_DAYS AND metrics.impressions > 100 ORDER BY metrics.conversions DESC

Ventilation des performances des appareils

SELECT campaign.name, segments.device, metrics.clicks, metrics.cost_micros, metrics.conversions FROM campaign WHERE segments.date DURING LAST_30_DAYS AND campaign.status = 'ENABLED'

📁 Structure du projet

google-ads-mcp-server/ ├── server.py # Serveur MCP principal ├── oauth/ │ ├── __init__.py # Initialisation du package │ └── google_auth.py # Logique d'authentification OAuth ├── google_ads_token.json # Stockage du jeton auto-généré (gitignored) ├── client_secret_[long-string].json # Vos identifiants OAuth (gitignored) ├─── .env # Variables d'environnement (gitignored) ├── .env.example # Modèle d'environnement ├── .gitignore # Fichier Git ignore ├── requirements.txt # Dépendances Python ├── LICENSE # Licence MIT └── README.md # Ce fichier

🔒 Sécurité et bonnes pratiques

Sécurité des fichiers

• ✅ Les fichiers d'identifiants sont gitignored - Jamais livrés au contrôle de version
• stockage local des jet ons - Les jetons sont stockés dans google_ads_token.json localement
• variables d'environnement - Données sensibles dans le fichier .env
• rafraîchissement automatique - Temps d'exposition minimal du jeton

Permissions de fichiers recommandées

# Définir des permissions sécurisées pour les fichiers sensibles chmod 600 .env chmod 600 google_ads_token.json chmod 600 client_secret_*.json

Considérations relatives à la production

1. Utiliser des variables d'environnement au lieu de fichiers .env en production
2. Mettre en place une limitation de débit pour respecter les quotas de l'API
3. Surveiller l'utilisation de l'API dans Google Cloud Console
4. Stockage sécurisé des jetons avec des contrôles d'accès appropriés
5. Rotation régulière des jetons pour une sécurité renforcée

🛠️ Dépannage

Problèmes d'authentification

Problèmes de configuration

Problèmes liés au bureau de Claude

Problèmes liés à l'API

Mode débogage

Activer la journalisation détaillée pour le dépannage :

# Ajouter à server.py pour le débogage importer logging logging.basicConfig(level=logging.DEBUG)

Obtenir de l'aide

Si vous rencontrez des problèmes :

1. Vérifiez attentivement le message d'erreur - il indique généralement le problème exact
2. Vérifiez que tous les chemins d'accès aux fichiers sont absolus et corrects
3. Assurez-vous que les variables d'environnement sont correctement définies
4. Vérifiez les quotas d'API et la facturation dansGoogle Cloud Console
5. Redémarrez Claude Desktop après toute modification de la configuration

🚀 Configuration avancée

Mode de transport HTTP

Pour un déploiement web ou un accès à distance :

# Démarrer le serveur en mode HTTP python3 server.py --http

Configuration de Claude Desktop pour HTTP :

{ "mcpServers" : { "google-ads" : { "url" : "http://127.0.0.1:8000/mcp" } }

Stockage personnalisé des jetons

Modifier l'emplacement du stockage des jetons dans oauth/google_auth.py:

# Emplacement du fichier de jetons personnalisé def get_token_path() : return "/custom/secure/path/google_ads_token.json"

Configuration du compte du gestionnaire

Pour gérer plusieurs comptes sous un MCC :

# Ajouter au fichier .env GOOGLE_ADS_LOGIN_CUSTOMER_ID=123-456-7890

🤝 Contribuer

Les contributions sont les bienvenues ! Voici comment commencer :

Développement

# Créer un dépôt git clone https://github.com/yourusername/google-ads-mcp-server.git cd google-ads-mcp-server # Créer un environnement de développement python3 -m venv .venv source .venv/bin/activate # Installer les dépendances pip install -r requirements.txt # Configurer l'environnement de développement cp .env.example .env # Ajouter vos identifiants de développement à .env

Effectuer des changements

1. Créez une branche de fonctionnalités :git checkout -b feature/amazing-feature
2. Effectuez vos modifications avec les tests appropriés
3. Testez minutieusement avec différentes configurations de compte
4. Mettre à jour la documentation si nécessaire
5. Validation des modifications :git commit -m 'Add amazing feature' (Ajouter une fonctionnalité étonnante)
6. Pousser vers la branche :git push origin feature/amazing-feature
7. Ouvrir une Pull Request avec une description détaillée

Tester vos modifications

# Tester le flux d'authentification python3 server.py --test-auth # Tester la connectivité API python3 -c " from oauth.google_auth import get_oauth_credentials creds = get_oauth_credentials() print('✅ Authentication successful!') " # Tester avec Claude Desktop # Ajouter votre serveur à Claude config et tester les différentes commandes

📊 Limites et quotas de l'API

Quotas de l'API Google Ads

• Accès de base : 15 000 opérations par jour
• Accès standard : 40 000 opérations par jour
• Taux de requête : 1 600 demandes par minute et par jeton de développeur

Meilleures pratiques pour l'utilisation de l'API

1. Mettez les résultats en cache lorsque cela est possible afin de réduire le nombre d'appels à l'API
2. Utiliser des plages de dates pour limiter le volume de données
3. Effectuerdes requêtes par lots lorsque cela est possible
4. Surveiller l'utilisation dans Google Cloud Console
5. Mettre en œuvre une logique de réessai pour les erreurs de limite de taux

Gestion des quotas

# Surveiller l'utilisation dans Google Cloud Console Aller dans APIs & Services → Quotas Rechercher "Google Ads API" pour voir l'utilisation actuelle

licence

Ce projet est sous licence MIT - voir le fichier LICENSE pour plus de détails.

Licence MIT

Copyright (c) 2025 Google Ads MCP Server Contributors L'autorisation est ici accordée, gratuitement, à toute personne obtenant une copie de ce logiciel et des fichiers de documentation associés (le "Logiciel"), de traiter le Logiciel sans restriction, y compris sans limitation les droits d'utilisation, de copie, de modification, de fusion, de publication, de distribution, de sous-licence, et/ou de vente de copies du Logiciel, et d'autoriser les personnes à qui le Logiciel est fourni à le faire, sous réserve des conditions suivantes : L'avis de copyright ci-dessus et cet avis d'autorisation doivent être inclus dans toutes les copies ou parties substantielles du Logiciel.

LE LOGICIEL EST FOURNI "TEL QUEL", SANS GARANTIE D'AUCUNE SORTE, EXPRESSE OU IMPLICITE, Y COMPRIS, MAIS SANS S'Y LIMITER, LES GARANTIES DE QUALITÉ MARCHANDE, D'ADÉQUATION À UN USAGE PARTICULIER ET D'ABSENCE DE CONTREFAÇON. EN AUCUN CAS LES AUTEURS OU LES DÉTENTEURS DES DROITS D'AUTEUR NE PEUVENT ÊTRE TENUS RESPONSABLES DE TOUTE RÉCLAMATION, DE TOUT DOMMAGE OU DE TOUTE AUTRE RESPONSABILITÉ, QUE CE SOIT DANS LE CADRE D'UNE ACTION CONTRACTUELLE, DÉLICTUELLE OU AUTRE, DÉCOULANT DE OU EN RAPPORT AVEC LE LOGICIEL OU L'UTILISATION OU D'AUTRES OPÉRATIONS LIÉES AU LOGICIEL

feuille de route

Fonctionnalités à venir

• 🔄 Recherche de mots-clés améliorée avec analyse des concurrents
• 📊 Visualisation de données intégrée avec diagrammes et graphiques
• 🤖 S uggestions d'optimisation alimentées par l'IA
• 📝 O utils de création et de gestion de campagnes
• 🔍 Capacités de reporting avancées
• 🌐 Prise en charge multilingue

Réalisé avec ❤️ pour la communauté MCP

Connectez vos données Google Ads directement aux assistants IA et débloquez de puissantes informations publicitaires grâce à des conversations en langage naturel.