cohnen/mcp-google-ads

This repository provides a tool that integrates Google Ads data with AI assistants like Claude and Cursor, enabling natural language analysis of advertising campaigns. It empowers advertising professionals and developers to query, understand, and optimize ad performance through conversational interfaces, abstracting the complexity of the Google Ads API.

How It Works

The project utilizes an MCP (Multi-Cloud Platform) server as a backend to interface with the Google Ads API. Users interact with AI assistants (Claude or Cursor), which then send requests to the MCP server. The server executes Google Ads Query Language (GAQL) queries to retrieve campaign, ad group, keyword, and performance data. This data is processed by the AI, allowing for conversational analysis, trend identification, and visualization.

Quick Start & Requirements

Installation involves cloning the repository, setting up a Python virtual environment (e.g., using uv or venv), and installing dependencies via requirements.txt. Key prerequisites include Python 3.11+, Node.js, and either Claude Desktop or Cursor. Crucially, users must obtain a Google Ads API Developer Token (approval may take 1-3 business days) and configure credentials via OAuth 2.0 Client ID or a Service Account JSON key file. Environment variables (GOOGLE_ADS_CREDENTIALS_PATH, GOOGLE_ADS_DEVELOPER_TOKEN, GOOGLE_ADS_AUTH_TYPE) must be set, with an optional GOOGLE_ADS_LOGIN_CUSTOMER_ID for Manager Accounts.

Highlighted Details

• Advanced GAQL: Supports arbitrary GAQL queries with flexible output formats (table, JSON, CSV).
• AI-Driven Insights: Enables conversational analysis, trend identification, and actionable optimization recommendations.
• Data Visualization: AI assistants can generate charts and graphs for metrics like trends, comparisons, and distributions.
• Cursor Integration: Facilitates combining code analysis with ad performance data directly within the development environment.

Maintenance & Community

Support and contributions are managed via GitHub issues/pull requests, with direct contact available for Ernesto Cohnen at ernesto@ixigo.com.

Licensing & Compatibility

The project is licensed under the permissive MIT License, allowing for broad compatibility with commercial and closed-source applications.

Limitations & Caveats

Setup requires familiarity with API credential management and environment variable configuration. Users may encounter Google Ads API quota limitations. Obtaining a Developer Token involves an approval process. Careful configuration of file paths and environment variables is essential for successful integration.