Google Advertising Data Interface for Claude AI

This connector establishes a robust link between your Google Ads advertising expenditure data and the Claude AI reasoning engine, facilitating in-depth operational analysis entirely through conversational text prompts. This integration furnishes immediate access to vital campaign schemas, quantifiable performance indicators (KPIs), keyword efficacy insights, and advertising asset administration—all accessible via direct dialogue with Claude.

Core Capabilities for Digital Marketing Practitioners

Account Portfolio Oversight
Consolidated view of all linked Google Ads client entities.
Retrieval of overarching account metadata and foundational campaign parameters.
Campaign Measurement & Narrative Generation
Identification of high-performing advertising initiatives.
Continuous tracking of exposure counts (impressions), interaction rates (clicks), conversion volumes, and budgetary expenditure.
Longitudinal analysis of performance trajectory over designated epochs.
Comparative studies across distinct timeframes to delineate variances.
Data Visualization: Claude generates graphical representations (charts, plots) of retrieved advertising metrics.
Keyword & Ad Creative Examination
Pinpointing keywords exhibiting superior or suboptimal engagement.
Assessment of textual and visual ad component effectiveness.
Review of Quality Scores and competitive positioning metrics.
Receipt of concrete, prescriptive guidance for campaign refinement.
Financial Control & Bidding Strategy
Scrutiny of allocated budget consumption and spending pace.
Evaluation of current bidding methodologies against achieved results.
Discovery of potential avenues for efficiency maximization.
Generation of data-informed suggestions for budget redistribution.

Architectural Schematic: Data Flow

subgraph "Interface Server Component"
    FastSrv[FastAPI Endpoint Handler] 
    ToolRegistry[Available Function Registry] 
    AuthModule[Credential Validation & Management]

    FastSrv -->|Exposes| ToolRegistry
    FastSrv -->|Leverages| AuthModule
end

subgraph "Google Advertising Functions"
    AcctLister[list_client_entities]
    GawlExecutor[execute_custom_gawl_query]
    CampaignSummarizer[retrieve_campaign_metrics]
    AdCreativeEvaluator[assess_ad_asset_efficacy]
    RawGawlRunner[run_unstructured_gawl]
end

ToolRegistry -->|Incorporates| AcctLister
ToolRegistry -->|Incorporates| GawlExecutor
ToolRegistry -->|Incorporates| CampaignSummarizer
ToolRegistry -->|Incorporates| AdCreativeEvaluator
ToolRegistry -->|Incorporates| RawGawlRunner

subgraph "Credentialing"
    OauthClient[OAuth 2.0 Client Configuration]
    SrvAcct[Service Credential Key]
    AdsCredentials[Google Ads API Credentials]

    OauthClient -->|Generates| AdsCredentials
    SrvAcct -->|Generates| AdsCredentials
end

Bridge -->|Communicates via Secured Channel with| GoogleAdsAPI[Official Google Ads Reporting Endpoint]
GoogleAdsAPI -->|Returns| AdDataPayload[Structured Advertising Datasets]
AdDataPayload -->|Subjected to Analysis by| Claude
AdDataPayload -->|Used for Plotting by| Claude
AdDataPayload -->|Can be utilized by| CodeEditor

AdsCredentials -->|Authorizes Access to| GoogleAdsAPI

subgraph "System Configuration"
    EnvironmentVars[Runtime Environment Variables] 
    ConfigFiles[Static Configuration Manifests]

    EnvironmentVars -->|Sets Parameters for| Bridge
    ConfigFiles -->|Sets Parameters for| Claude
    ConfigFiles -->|Sets Parameters for| CodeEditor
end

Exposed Utility Functions

Once the system is operational, instruct Claude using these defined procedures:

Requested Action	Underlying Operation	Mandatory Input Parameters
`list_client_entities`	Enumerates all accessible Google Ads client organizations.	None required; simple invocation suffices.
`execute_custom_gawl_query`	Processes a structured Google Ads Query Language instruction.	Client Entity ID and the complete GAQL statement.
`retrieve_campaign_metrics`	Delivers aggregated performance statistics for specified campaigns.	Client Entity ID and the required temporal scope (date range).
`assess_ad_asset_efficacy`	Provides granular evaluation of individual ad creative success.	Client Entity ID and the relevant measurement period.
`run_unstructured_gawl`	Executes arbitrary GAQL, supporting customizable output serialization.	Client Entity ID, the query string, and desired format (tabular, JSON, or delimited text).

Advanced Query Execution (`run_unstructured_gawl`)

This function grants maximum flexibility by permitting direct submission of Google Ads Query Language (GAQL) syntax. Illustrative syntax examples:

Example 1: Core Campaign Metrics

sql SELECT campaign.name, metrics.clicks, metrics.impressions FROM campaign WHERE segments.date DURING LAST_7DAYS

Example 2: Ad Group Performance Profiling

sql SELECT ad_group.name, metrics.conversions, metrics.cost_micros FROM ad_group WHERE metrics.clicks > 100

Example 3: Keyword Engagement Review

sql SELECT keyword.text, metrics.average_position, metrics.ctr FROM keyword_view ORDER BY metrics.impressions DESC

To obtain a comprehensive inventory of all callable procedures and their precise operational signatures, query Claude with: "enumerate available procedures".

Implementation Guide (Zero-Code Entry Possible)

1. Establishing API Authorization

Prior to tool utilization, you must provision API credentials enabling secure access to your Google Ads repository. Two primary authorization pathways exist:

Pathway A: OAuth 2.0 Client Identifier (User-Delegated Access)

Optimal for single practitioners or locally hosted application contexts:

Navigate to the Google Cloud Console
Instantiate a new project or select an existing container.
Activate the Google Ads API within the project context.
Access "Credentials" → "Create Credentials" → "OAuth Client ID".
Designate the application type as "Desktop Application".
Secure the resulting OAuth client configuration payload (e.g., client_secret.json).
Secure a requisite Google Ads API Developer Token (refer to subsequent steps).

Pathway B: Service Account (Automated Server-to-Server Access)

Superior for continuous background processes or large-scale entity management:

Navigate to the Google Cloud Console
Instantiate a new project or select an existing container.
Activate the Google Ads API.
Access "Credentials" → "Create Credentials" → "Service Account".
Download the service account credential artifact (JSON format).
Explicitly delegate access rights for this service principal to your target Google Ads accounts.
Secure a requisite Google Ads API Developer Token.

Credential Lifecycle Management

The integration incorporates sophisticated mechanisms for token refreshment:

OAuth 2.0 Tokens: The system autonomously endeavors to renew lapsed OAuth tokens, falling back to user re-authentication if the refresh token itself is invalidated.
Service Account Tokens: Credentials derived from service accounts are automatically re-issued and managed internally without operator intervention.

Authorization Modality Comparison

Select OAuth 2.0 Client ID if:

Deployment targets a desktop application environment.
User consent must be explicitly obtained for each session or access grant.
Management scope is limited to a solitary entity or a small cohort of personal accounts.
Granular user control over access privileges is paramount.

Select Service Account if:

Deployment targets autonomous, headless operational procedures.
Server-to-server communication is the required access method.
Programmatic management of numerous client entities is necessary.
Minimizing required user intervention for continuous authentication is desired.

Procuring the Developer Token

Log into your primary Google Ads portal at https://ads.google.com.
Click the Configuration icon (wrench symbol) in the top navigation bar.
Under the "Setup" grouping, select "API Center".
Accept the requisite API Terms of Service if not yet completed.
Initiate the "Apply for token" workflow.
Complete the application form detailing the intended API usage pattern.
Submit for review; approval typically requires 1–3 standard business days.

Note: The initial token issued functions in a restricted 'test' mode. Upon successful validation of your implementation, apply for the production-grade token to eliminate usage constraints.

Understanding the Manager Customer Identifier

The GOOGLE_ADS_LOGIN_CUSTOMER_ID parameter serves a specific role, primarily invoked when:

Interfacing with a Google Ads Manager Account structure (MCC).
Requiring access to subordinate client entities via the Manager Account's credentials.

The Login Customer ID must correspond to your Manager Account identifier (format: XXX-XXX-XXXX) if:

You are aggregating data from multiple linked accounts.
You intend to utilize the Manager Account's credentials for scoping client access.

You may omit this configuration if:

Operation is restricted to a solitary, direct Google Ads entity.
Credentials are being sourced directly from the target entity itself.

To ascertain your Manager Account ID:

Log into the Manager Account interface.
Select the settings symbol (gear).
The Manager Account ID, formatted XXX-XXX-XXXX, will be visible.
Ensure the credentials file downloaded corresponds to this Manager Account context.

🎬 Instructional Video: COMING SOON

2. Prerequisite Software Acquisition

You must have the following foundational components operational on your host machine:

Python (Minimum version 3.11 recommended) - This runtime executes the bridge server logic.
Node.js - Necessary dependency for running the interface inspector and certain peripheral components.
Claude Desktop - The conversational interface software.

Confirm both Python and Node.js are correctly placed within your system's execution path prior to continuation.

3. Obtaining the Interface Package

Download the source code bundle for this utility:

Navigate to the primary repository page.
Select the "Code" button (usually green).
Choose the "Download ZIP" option.
Decompress the archive into a readily accessible file location (e.g., your user Documents folder).

Alternatively, for users proficient with version control:

bash git clone https://github.com/ixigo/mcp-google-ads.git

4. Installing Dependencies and Environment Setup

Open your system's command-line interface (Terminal on macOS/Linux, Command Prompt/PowerShell on Windows):

Traverse into the directory containing the extracted files:

bash # Adjustment required for your specific extraction path: cd ~/Documents/mcp-google-ads-main

Establish an isolated Python virtual environment (for dependency containment):

bash # Recommended utility (uv): uv venv .venv

# Installation instruction for uv if prerequisite is missing: pip install uv # Re-run environment creation: uv venv .venv

# Standard Python mechanism: python -m venv .venv

Advisory: Should you encounter a "pip not found" diagnostic, refer to the troubleshooting section below for resolution.

Activate the newly created environment:

bash # For macOS/Linux: source .venv/bin/activate

# For Windows: .venv\Scripts\activate

Deploy required libraries listed in the manifest:

bash # Using uv: uv pip install -r requirements.txt

# Using standard pip: pip install -r requirements.txt

# As a fallback, install the core interface package directly: pip install mcp

Resolution for "pip not found" Diagnostic:

bash # First, ensure pip is available and current: python3 -m ensurepip --upgrade python3 -m pip install --upgrade pip

# Reattempt dependency installation: python3 -m pip install -r requirements.txt

# Then attempt uv installation: python3 -m pip install uv

Your prompt prefix displaying (.venv) confirms the isolated environment is active, ensuring dependencies are scoped locally.

5. Configuring Runtime Parameters

The Ads Interface supports simplified provisioning via an environment parameter file.

Utilizing the `.env` File (Preferred Method)

Duplicate the template file to create the active configuration file:

bash cp .env.example .env

Edit the .env document using your preferred text editor to input confidential settings:

bash # For macOS (via built-in editor): nano .env

# For Windows: notepad .env

Populate the following variables within .env:

# Authentication Selection: Must be set to "oauth" or "service_account" GOOGLE_ADS_AUTH_TYPE=oauth

# Absolute file system path to your credentials artifact (OAuth secret or Service Account JSON key) GOOGLE_ADS_CREDENTIALS_PATH=/path/to/your/credentials.json

# Your Registered Google Ads Developer Token GOOGLE_ADS_DEVELOPER_TOKEN=your_developer_token_here

# Optional: Manager Account ID, if accessing subordinate entities GOOGLE_ADS_LOGIN_CUSTOMER_ID=your_manager_account_id

Save and close the configuration manifest.

The application automatically reads these parameters upon server startup.

Direct System Environment Variables

Alternatively, settings can be injected directly into the execution environment manifest for Claude or Cursor:

For Claude Desktop Configuration File

{ "mcpServers": { "googleAdsServer": { "command": "/FULL/PATH/TO/mcp-google-ads-main/.venv/bin/python", "args": ["/FULL/PATH/TO/mcp-google-ads-main/google_ads_server.py"], "env": { "GOOGLE_ADS_AUTH_TYPE": "oauth", "GOOGLE_ADS_CREDENTIALS_PATH": "/FULL/PATH/TO/mcp-google-ads-main/credentials.json", "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN_HERE", "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "YOUR_MANAGER_ACCOUNT_ID_HERE" } } } }

For Cursor Configuration File

Crucial Note: Substitute all placeholder paths and security values with your specific, absolute file locations and secrets.

6. Finalizing the Claude Connection Bridge

Ensure you possess the Claude Desktop application installed.
Verify your Service Account JSON credential file is stored securely.
Initiate the system configuration file modification via the command line:

bash

macOS Users:

nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows Users:

notepad %APPDATA%\Claude\claude_desktop_config.json

Inject the following structural configuration (adjusting paths as necessary):

{ "mcpServers": { "googleAdsServer": { "command": "/FULL/PATH/TO/mcp-google-ads-main/.venv/bin/python", "args": ["/FULL/PATH/TO/mcp-google-ads-main/google_ads_server.py"], "env": { "GOOGLE_ADS_CREDENTIALS_PATH": "/FULL/PATH/TO/mcp-google-ads-main/service_account_credentials.json", "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN_HERE", "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "YOUR_MANAGER_ACCOUNT_ID_HERE" } } } }

Mandatory Adjustments:

Path 1: Must point to the Python executable within your active virtual environment.
Path 2: Must point to the google_ads_server.py script within the extracted project folder.
Path 3: Must reference the location of your Google Service Account JSON artifact.
Populate your specific Developer Token and Manager Account ID.
Persist the file changes:
Mac: Ctrl+O, Enter, Ctrl+X.
Windows: File menu → Save, then close the editor.
Relaunch the Claude Desktop application.
Upon initialization, the Google Ads capabilities should now be registered within Claude's accessible toolset.

5a. Enabling Cursor Integration (Development Workflow)

Cursor, an AI-augmented coding editor, can leverage these advertising insights directly within the development context.

Cursor Configuration Procedure

If absent, install the Cursor editor.
Establish a configuration manifest file named .cursor/mcp.json within your active development workspace, OR create a global configuration at ~/.cursor/mcp.json.
Integrate the service definition into this file:

{ "mcpServers": { "googleAdsServer": { "command": "/FULL/PATH/TO/mcp-google-ads-main/.venv/bin/python", "args": ["/FULL/PATH/TO/mcp-google-ads-main/google_ads_server.py"], "env": { "GOOGLE_ADS_CREDENTIALS_PATH": "/FULL/PATH/TO/mcp-google-ads-main/service_account_credentials.json", "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN_HERE", "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "YOUR_MANAGER_ACCOUNT_ID_HERE" } } } }

Crucial Note: Ensure path and token accuracy as detailed in Step 6.

Refresh Cursor or reload the project workspace to activate the new configuration.
The Google Ads capability will now be selectable in Cursor's "Available Tooling" listing.

Utilizing Ads Data within Cursor Prompts

Instruct Cursor's AI agent to invoke the integrated procedures contextually. Examples:

"Query the Google Ads MCP to enumerate all active accounts and identify the entity with the highest aggregate expenditure this calendar month."
"Employ the Ads MCP to generate a summarized performance report for campaigns running over the preceding 30-day interval."
"Execute a customized GAQL retrieval via the Ads tools to isolate top-performing keywords based on conversion volume."

Cursor will typically prompt for authorization before execution (unless configured otherwise) and render the query results directly in the interface panel.

Advanced Cursor Synergy

This specific coupling allows for:

Integrated Code Review & Data Validation: Analyze application code alongside real-time advertising performance evidence.
Automated Visualization Generation: Request charts depicting ad efficacy directly within the IDE.
Data-Driven Code Refinement: Receive code suggestions from Cursor informed by actual marketing metrics.

This feature set is particularly potent for development teams building marketing tech, analytics pipelines, or e-commerce platforms where advertising success metrics directly influence code logic.

7. Commencement of Advertising Data Interrogation!

You are now equipped to converse with Claude regarding your Google Ads statistics! Claude can not only fetch raw data but also interpret temporal patterns, synthesize findings, and chart metrics to enhance performance comprehension.

Recommended conversational starting points for each utility:

| Procedure Name | Exemplary Instruction | |---------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|| | list_client_entities | "Catalogue every Google Ads entity I manage and specify which entity incurred the largest portion of this month's expenditure." | execute_custom_gawl_query | "For account 123-456-7890, execute: SELECT campaign.name, metrics.clicks FROM campaign WHERE metrics.impressions > 1000" | retrieve_campaign_metrics | "Present the top 10 performing campaigns for account 123-456-7890 covering the last 30 days. Flag any instances where Return On Ad Spend (ROAS) falls below 2.0 and propose immediate corrective measures." | assess_ad_asset_efficacy | "Conduct a deep-dive analysis on the performance differential between ad copy variants, emphasizing elements that drive superior Click-Through Rates (CTR). Deliver specific, implementable recommendations." | run_unstructured_gawl | "Execute the following query, outputting the result set in CSV format: SELECT ad_group.name, metrics.clicks, metrics.conversions FROM ad_group WHERE campaign.name LIKE '%Brand%Keywords%'"

Furthermore, Claude excels at chaining tool invocations for comprehensive analysis. For instance:

"Retrieve the top 20 highest converting keywords, subsequently fetch their current Quality Scores and impression share metrics, and synthesize a report highlighting immediate scaling opportunities."
"Analyze the overall account trend across the past quarter (90 days), pinpoint the fastest expanding campaign clusters, and ascertain if any current budgetary ceilings are impeding their continued growth."
"Establish a performance comparison matrix between desktop and mobile advertising results, generate comparative graphical data representations, and suggest granular mobile bid adjustments based on identified performance deficiencies."
"Identify all advertising instances where expenditure is being allocated to search terms not present in my designated positive keyword list, and recommend which of those unlisted terms should be formalized as exact-match inclusions."

Claude will systematically invoke the necessary Google Ads procedures, format the returned datasets for clarity, generate relevant visualizations, and formulate actionable strategic advice derived directly from the retrieved metrics.

Data Visualization Potential

Claude significantly enhances data comprehension through graphical presentation:

Temporal Trend Analysis: Visualize metric fluctuations across time.
Comparative Plotting: Contrast performance across disparate campaigns or ad components.
Audience Segmentation: Display performance distributions segmented by device type or demographic.
Correlation Mapping: Determine relationships between financial inputs (cost) and outcome measures (conversions).
Density Representation: Employ heatmaps for interpreting high-dimensional datasets.

Simply instruct Claude to "render a visualization" or "chart the data" during any analysis task to unlock these visual aids.

Diagnostic and Remediation Procedures

Python Execution Path Errors

On systems defaulting to python as an alias for an older version (common on macOS), Node.js components may fail to locate the required Python 3 runtime.

Remedy: Establish a symbolic link (one-time administrative action):

Create Alias: bash # For macOS users: sudo ln -s $(which python3) /usr/local/bin/python

# Alternative path resolution if the primary fails: sudo ln -s /Library/Frameworks/Python.framework/Versions/3.11/bin/python3 /usr/local/bin/python

Confirm Link Integrity:

bash python --version

This action ensures that calls to the generic python command correctly target your installed Python 3 binary.

Interface Configuration Failures

If connectivity issues persist with Claude:

Double-check that all absolute file system paths in your configuration JSON are perfectly accurate.
Confirm the designated Service Account possesses explicit read permissions within the linked Google Ads client accounts.
Validate the entered Developer Token against the Google Ads API Center.
Always execute a full restart of the Claude Desktop client following any modification to its configuration file.
Scrutinize Claude's response messages for explicit diagnostic feedback when invoking a tool.
Ensure your execution environment (virtual environment) is correctly initialized when manually running the server component.

Google Ads API Quota Constraints

Errors indicative of hitting rate limits or permission issues:

Inspect the API call quota status within the Google Cloud Console for the associated project.
Verify that the Developer Token holds the requisite access tier.
Confirm that the Service Account is correctly provisioned with necessary scopes.

Unforeseen Problems

Should non-standard execution errors materialize:

Capture the complete, verbatim error log output.
Direct an inquiry to Ernesto Cohnen at ernesto@ixigo.com, providing:
The precise operational goal you were pursuing.
The exact error message text.
Your operating system specification.
A list of troubleshooting steps already undertaken.

Consultation with general-purpose AI assistants can often yield immediate tactical advice for resolving specific technical hurdles.

Note: Nearly all deployment obstacles have pre-existing documented resolutions; systematic checking is usually sufficient.

Validation of Operational Readiness

The repository integrates test scripts to confirm API connectivity integrity separate from the Claude/Cursor orchestration layer.

Executing Standard Functionality Tests

Activate the virtual environment (refer to Step 4 instructions).
Configure Credentials in the Test Script:
Open test_google_ads_mcp.py.
Locate the conditional environment check block (starting if not os.environ.get(...)).
Update the placeholder values with your credentials, or comment out this block if environment variables are set externally.
Execute the primary validation script: bash python test_google_ads_mcp.py
The script sequence performs:
Enumeration of all accessible Google Ads memberships.
Retrieval of campaign performance data utilizing the first found account ID.
Validation of ad creative data retrieval.
Execution of a representative GAQL statement.

Testing Authorization & Token Refresh Cycles

To specifically validate the credential persistence and renewal logic:

Ensure environment configuration (via .env or shell export) is complete.
Execute the specialized refresh tester: bash python test_token_refresh.py
This test confirms:
Successful credential loading based on the configured authentication method (OAuth/SA).
Display of current token metadata and expiration status.
Successful execution of the token renewal routine (particularly vital for OAuth flows).

Successful completion of all validation routines confirms the bridge server is fully configured and ready for integration with Claude or Cursor.

Collaborative Contributions

Encountered a defect or conceived an enhancement? We welcome contributions! Initiate a discussion by filing an issue or submitting a Pull Request on the GitHub repository, or reach out directly to Ernesto Cohnen at ernesto@ixigo.com.

Licensing Declaration

This software is released under the terms of the MIT License. Consult the LICENSE file for comprehensive particulars.

Contextual Information (ixigo & Business Tooling)

ixigo powers India's foremost travel aggregation platform, assisting countless travelers daily with optimal pricing for air, rail, road transport, and lodging. More details available at ixigo.com.

REFERENCE WIKIPEDIA: Business management systems encompass the totality of frameworks, applications, control mechanisms, computational solutions, and guiding principles employed by enterprises to effectively navigate evolving market dynamics, maintain competitive standing, and elevate overall operational efficacy.

== High-Level Summary == Management tooling is departmentally specialized, categorized by functional aspects such as strategic foresight, process administration, record-keeping, personnel management, critical decision support, and performance governance. The technological acceleration of the last decade has profoundly reshaped this landscape, creating complexity in selecting optimal solutions amidst constant market pressures for cost reduction and sales maximization, alongside the necessity of deep customer need comprehension. Managers must adopt a strategic posture toward these tools, ensuring they are methodically adapted to organizational specifics rather than blindly adopting the newest release.

== Prevalent Tools (2013 Survey Insights) == The Bain & Company survey indicated common high-priority tools globally, reflecting regional needs and market conditions:

Strategic Planning
Customer Relationship Management (CRM)
Employee Sentiment Analysis
Performance Benchmarking
Balanced Scorecard Implementation
Core Competency Mapping
Business Process Outsourcing (BPO)
Organizational Change Management Programs
Supply Chain Optimization
Mission and Vision Articulation
Market Segmentation Strategy
Total Quality Management (TQM)

== Business Software Applications == Business software refers to collections of programs utilized by personnel to execute diverse corporate functions, intended to augment productivity and ensure precise operational measurement. This domain evolved from early Management Information Systems (MIS) through Enterprise Resource Planning (ERP) and later incorporating CRM, now frequently residing in cloud-native environments. While IT investment correlates with organizational performance, success hinges critically on both the efficacy of deployment and the judicious selection and customization of the implemented tools.

== Tools Tailored for Small/Medium Enterprises (SMEs) == SME-focused tooling is vital as it delivers mechanisms designed to conserve operational capital...

mcp-google-ads-analytics-bridge

Author

cohnen

Quick Info

Actions

Tags