Serveur MCP Google Ads API v20

Serveur MCP (Model Context Protocol) complet qui offre un accès intégral aux fonctionnalités de l'API Google Ads v20. Ce serveur permet aux assistants d'intelligence artificielle d'effectuer n'importe quelle opération Google Ads par le biais de commandes en langage naturel.

Caractéristiques

Couverture complète de l'API

• Gestion des comptes: Liste des comptes, obtention d'informations sur les comptes, affichage de la hiérarchie
• Gestion des campagnes: Création, mise à jour, pause/reprise des campagnes avec toutes les fonctionnalités de la v20
• Gestion des groupes de publicités: Opérations CRUD complètes pour les groupes de publicités
• Création de publicités: Annonces de recherche réactives, annonces textuelles élargies, etc
• Gestion des ressources: Téléchargement et gestion d'images et de textes
• Gestion du budget: Création et gestion de budgets partagés
• Gestion des mots-clés: Ajouter des mots-clés, des mots-clés négatifs (y compris les mots-clés négatifs de la campagne Performance Max)
• Rapports et analyses: Requêtes GAQL personnalisées, rapports de performance, termes de recherche
• Fonctionnalités avancées: Recommandations, historique des modifications, expériences

Fonctionnalités intelligentes

• Logique de réessai automatique: Gère les erreurs transitoires avec un backoff exponentiel
• Documentation des erreurs: Liens vers la documentation officielle sur les erreurs de l'API Google Ads
• Gestion des échecs partiels: Poursuite du traitement en cas d'échec de certaines opérations
• Rafraîchissement automatique des jetons: Actualisation automatique des jetons OAuth
• Réécriture automatique: Peut consulter la documentation et réessayer les opérations qui ont échoué

Installation

# Installer avec pip pip install -e . # Ou installer les dépendances directement pip install mcp google-ads pydantic httpx tenacity python-dotenv beautifulsoup4 structlog

Configuration de l'environnement

Variables d'environnement

Créez un fichier .env ou définissez ces variables d'environnement :

# Authentification OAuth2 GOOGLE_ADS_CLIENT_ID=votre_identification_client GOOGLE_ADS_CLIENT_SECRET=votre_secret_client GOOGLE_ADS_REFRESH_TOKEN=votre_refresh_token # OU Authentification du compte de service GOOGLE_ADS_SERVICE_ACCOUNT_PATH=/path/to/service-account.json GOOGLE_ADS_IMPERSONATED_EMAIL=user@example.com # Optionnel # Requis pour toutes les méthodes d'authentification GOOGLE_ADS_DEVELOPER_TOKEN=votre_token de développeur GOOGLE_ADS_LOGIN_CUSTOMER_ID=1234567890 # ID du compte manager si applicable

Fichier de configuration

Vous pouvez également créer un fichier de configuration dans ~/.config/google-ads-mcp/config.json:

{"client_id" : "your_client_id", "client_secret" : "your_client_secret", "refresh_token" : "your_refresh_token", "developer_token" : "your_developer_token", "login_customer_id" : "1234567890" }

Configuration MCP

Ajoutez à votre configuration Claude Desktop(~/.config/claude/mcp.json) :

{ "mcpServers" : { "google-ads" : { "command" : "python", "args" : ["-m", "google-ads-mcp"], "env" : {"GOOGLE_ADS_DEVELOPER_TOKEN" : "votre_token", "GOOGLE_ADS_CLIENT_ID" : "your_client_id", "GOOGLE_ADS_CLIENT_SECRET" : "votre_secret", "GOOGLE_ADS_REFRESH_TOKEN" : "your_refresh_token" } } } }

Exemples d'utilisation

Opérations de base

# Lister tous les comptes Utiliser l'outil list_accounts # Créer une campagne Utiliser create_campaign avec customer_id="1234567890", name="Summer Sale 2025", budget_amount=100.0, campaign_type="SEARCH" # Obtenir les performances de la campagne Utiliser get_campaign_performance avec customer_id="1234567890", date_range="LAST_30_DAYS"

Requêtes avancées

# Exécuter une requête GAQL personnalisée Utiliser run_gaql_query avec la requête : SELECT campaign.name, metrics.clicks, metrics.conversions FROM campaign WHERE metrics.impressions > 1000 AND segments.date DURING LAST_7_DAYS ORDER BY metrics.clicks DESC

Fonctionnalités de Performance Max (v20)

# Ajouter des mots-clés négatifs à la campagne Performance Max Utiliser add_negative_keywords avec customer_id="1234567890", campaign_id="123", keywords=["cheap", "discount", "free"]

Gestion des erreurs

Le serveur fournit des informations détaillées sur les erreurs :

• Type et code d'erreur
• Message lisible par l'homme
• Si l'erreur peut être réessayée
• Lien vers la documentation officielle
• Suggestions pour corriger les erreurs courantes

Développement

Exécution des tests

pytest tests/

Ajouter de nouveaux outils

1. Ajouter la définition de l'outil à _register_tools() dans tools.py
2. Implémentation de la méthode handler
3. Mise à jour de la documentation

Débogage

# Exécuter avec la journalisation de débogage export LOG_LEVEL=DEBUG python -m google-ads-mcp

Notes de sécurité

• Ne jamais livrer les informations d'identification au contrôle de version
• Utiliser des comptes de service pour les environnements de production
• Activer le 2FA sur les comptes Google Ads
• Effectuer une rotation régulière des jetons de rafraîchissement
• Surveiller l'utilisation de l'API et définir des alertes

Prise en charge de la version de l'API

Ce serveur est conçu pour l'API Google Ads v20 (sortie en juin 2025) et comprend :

• Mots-clés négatifs au niveau de la campagne pour Performance Max
• Rapports améliorés sur la génération de demande avec segmentation des canaux
• Conversions comparables à celles de la plateforme
• Toutes les fonctionnalités et améliorations spécifiques à la v20

Licence

Licence MIT - Voir le fichier LICENSE pour plus de détails

Contribuer

Les contributions sont les bienvenues ! S'il vous plaît :

1. Mettre le dépôt en fourche (Fork)
2. Créer une branche de fonctionnalités
3. Ajouter des tests pour les nouvelles fonctionnalités
4. Soumettre une demande d'extraction

Support

Pour les problèmes et les questions :

• Consultez la documentation de l'API Google Ads
• Consultez les messages d'erreur et les liens de la documentation
• Ouvrir un problème sur GitHub