Google Ads MCP Server

A Model Context Protocol (MCP) server written in Python that exposes the Google Ads API to LLM clients (like Claude Desktop, Cursor, or Antigravity AI).

This server allows the LLM to inspect customer account lists, run custom Google Ads Query Language (GAQL) queries, format output (Markdown Tables, CSV, JSON), retrieve detailed performance reports for campaigns, ads, keywords, search terms, device types, and geographies, audit account change status log, inspect remarketing list definitions, and execute campaign management mutates.

It fully supports campaign types like Search, Performance Max (PMax), Demand Gen, and Store Visits (Local).

---

Registered MCP Tools

The server registers 21 tools categorized below:

1. Account & Query Management

• list_accounts: Lists all customer IDs under your credentials. If your credentials link to a Manager (MCC) Account, it automatically fetches and details all nested sub-accounts (ID, name, status, manager flag).
• run_gaql: Executes a raw GAQL SELECT query. Supports custom output format (table for Markdown, csv, or json).
• search_google_ads: Alias for run_gaql returning JSON.

2. Marketing Analytics & Reporting

• get_campaign_performance: Fetches campaign metrics (Impressions, Clicks, CTR, Cost, CPC, Conversions, CPA, Conversion Value) for a date range. Cost is formatted in standard currency units (not micros).
• get_ad_performance: Fetches metrics for specific ad creatives, mapped to Campaign/Ad Group.
• get_keyword_performance: Fetches performance for keywords, including Google Quality Scores.
• get_search_term_report: Fetches the search term query log triggered by ads, which helps identify positive keywords and negative keyword candidates.
• get_device_performance: Segment performance metrics by device type (MOBILE, DESKTOP, TABLET, etc.).
• get_geo_performance: Segment performance metrics by geographic location (Country, State, Metro).
• get_recommendations: Fetches active optimization recommendations and potential score impact directly from the Google Ads AI engine.
• get_change_status: Audits recent change events in the account to see what resources (campaigns, ad groups, criteria, ads) were modified and when.
• list_user_lists: Lists remarketing lists and custom audiences defined in the account along with their search/display audience sizes.

3. Creation & Mutation Management (Campaign Types Support)

• create_campaign_budget: Set up a campaign budget.
• create_campaign: Set up a campaign supporting Search, Performance Max, Demand Gen, Store Visits (Local), Display, Shopping, and Video networks. Set advertising_channel_type to SEARCH, PERFORMANCE_MAX, DEMAND_GEN, LOCAL, DISPLAY, SHOPPING, or VIDEO.
• create_asset_group: Set up an Asset Group under a Performance Max campaign. Note: Performance Max campaigns require Asset Groups instead of traditional Ad Groups.
• create_ad_group: Set up a traditional ad group under a campaign (used for Search, Display, Shopping, etc.).
• create_responsive_search_ad: Set up ads with headlines, descriptions, and final URLs.
• create_keywords: Bulk add keywords to an ad group.
• create_negative_keywords: Add broad-match negative keywords directly to campaigns or ad groups. It dynamically resolves the target type by looking at the resource name.
• update_campaign_status: Pauses, enables, or removes a campaign.
• update_ad_group_status: Pauses, enables, or removes an ad group.

---

Configuration

To interact with the Google Ads API, the server requires OAuth 2.0 and developer credentials passed via environment variables.

Environment Variables

Variable	Description
GOOGLE_ADS_DEVELOPER_TOKEN	Your Google Ads Developer Token.
GOOGLE_ADS_CLIENT_ID	OAuth 2.0 Client ID (from Google Cloud Console).
GOOGLE_ADS_CLIENT_SECRET	OAuth 2.0 Client Secret (from Google Cloud Console).
GOOGLE_ADS_REFRESH_TOKEN	OAuth 2.0 Refresh Token (generated after user authorization).
GOOGLE_ADS_LOGIN_CUSTOMER_ID	(Optional) Required if the refresh token is associated with a Manager (MCC) account. Set to the MCC Account ID (without dashes, e.g. 1234567890).

---

Installation & Setup

You can install and run this MCP server on any local machine (Windows, macOS, or Linux).

Prerequisites

• Python 3.10 or higher installed on your machine.
• A Google Ads Developer Account and OAuth2 credentials.

1. Clone the Repository

Clone this repository to your local machine:

git clone https://github.com/pralayasimha23/google-ads-mcp-connector.git
cd google-ads-mcp-connector

2. Set Up Virtual Environment & Dependencies

Create a virtual environment and install the required dependencies:

On Windows:

python -m venv venv
.\venv\Scripts\activate
pip install -r requirements.txt

On macOS/Linux:

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

3. Configure Credentials

You can define your credentials in a .env file in the root directory of the project: Create a .env file:

GOOGLE_ADS_DEVELOPER_TOKEN=your_developer_token
GOOGLE_ADS_CLIENT_ID=your_client_id
GOOGLE_ADS_CLIENT_SECRET=your_client_secret
GOOGLE_ADS_REFRESH_TOKEN=your_refresh_token
GOOGLE_ADS_LOGIN_CUSTOMER_ID=your_manager_customer_id_if_applicable

Alternatively, you can pass them as environment variables directly when launching the server, or within your MCP client configuration file (e.g., Claude Desktop, Cursor).

4. Run the Server Locally

To start the MCP server manually (for testing or via stdio integration):

# Verify it runs and connects successfully
python server.py

---

Client Integration

1. Claude Desktop

Add the following block to your Claude Desktop configuration file (located at %APPDATA%\Claude\claude_desktop_config.json on Windows, or ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "google-ads": {
      "command": "/path/to/your/google-ads-mcp-connector/venv/bin/python",
      "args": [
        "/path/to/your/google-ads-mcp-connector/server.py"
      ],
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN",
        "GOOGLE_ADS_CLIENT_ID": "YOUR_CLIENT_ID",
        "GOOGLE_ADS_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
        "GOOGLE_ADS_REFRESH_TOKEN": "YOUR_REFRESH_TOKEN",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "YOUR_MANAGER_CUSTOMER_ID_IF_MCC_ACCOUNT"
      }
    }
  }
}

(Note: For Windows, use double-backslashes \\ in paths, and point to venv\\Scripts\\python.exe)

2. Antigravity IDE / Antigravity 2.0

If you are using the Antigravity IDE:

1. You can run the configuration script to automatically register it:

   python configure_local_mcp.py
   

2. Or manually add the configuration under the mcpServers property in C:\Users\prala\.gemini\config\mcp_config.json (pointing to your local project directory path).