# google-ads [Health: Active]

**Category:** 🎯 Marketing  
**Repository:** https://github.com/mharnett/mcp-google-ads  
**GitHub Stars:** 1  
**npm Downloads (last month):** 1280  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/google-ads-8

## Description
Google Ads MCP with MCC support: 35 tools for campaigns, keywords, reporting, GAQL.

## Tools
Capabilities this server exposes over MCP:

- **google_ads_get_client_context** — Get the current client context and health status based on working directory. Call this first to confirm which Google Ads account you're working with.
- **google_ads_list_campaigns** — List all campaigns for the current client account
- **google_ads_list_ad_groups** — List ad groups, optionally filtered by campaign
- **google_ads_get_campaign_tracking** — Get campaign tracking parameters including tracking URL template, final URL suffix, and custom URL parameters
- **google_ads_list_pending_changes** — List all pending changes (paused items with claude- label) awaiting review
- **google_ads_validate_ad** — Validate an RSA without creating it. Use this to check for errors before creating. Enforces: 3-15 headlines (≤30 chars), 2-4 descriptions (≤90 chars), ≥1 final URL, both path1 AND path2 present (≤15 chars each), ≥1 label.
- **google_ads_keyword_performance** — Get keyword performance report with metrics including impressions, clicks, cost, conversions, quality score components (quality score, expected CTR, ad relevance, landing page experience), and impression share metrics.
- **google_ads_keyword_performance_by_conversion** — Get keyword performance broken down by conversion action. Shows which keywords drive which conversion types (e.g., form fills, MQLs, etc.).
- **google_ads_search_term_report** — Get search term report showing actual search queries that triggered ads, with the keyword they matched to.
- **google_ads_search_term_report_by_conversion** — Get search term report broken down by conversion action. Shows which search queries drive which conversion types.
- **google_ads_ad_performance** — Get ad performance report with metrics, ad copy (headlines/descriptions), final URLs, and ad strength rating.
- **google_ads_ad_performance_by_conversion** — Get ad performance broken down by conversion action. Shows which ads drive which conversion types.
- **google_ads_list_conversion_actions** — List all available conversion actions (e.g., form fills, MQLs, etc.) to understand what conversion tracking is set up.
- **google_ads_search_term_insights** — Get search term category insights for a campaign. Shows the search categories your ads appeared against (like the Insights panel in the Google Ads UI). Must query one campaign at a time. Optionally compares two date ranges to show trends.
- **google_ads_search_term_insight_terms** — Drill into a specific search term category to see the individual search terms within it. Requires an insight_id from google_ads_search_term_insights.
- **google_ads_get_campaign_diagnostics** — Diagnose why a campaign is not spending or serving. Returns primary_status, primary_status_reasons, serving_status, budget, bidding strategy, and last-7-days metrics in a single call. Use this as the first step when a campaign has unexpectedly low spend or impressions.
- **google_ads_get_ad_strength** — Get the ad strength rating (POOR, AVERAGE, GOOD, EXCELLENT) for RSAs in a campaign or ad group, along with headline/description counts. Ad strength below GOOD suppresses delivery. Use this to identify ads that need more creative assets.
- **google_ads_gaql_query** — Execute a raw GAQL (Google Ads Query Language) query. Use this for custom reports or accessing any Google Ads API resource not covered by other tools. See https://developers.google.com/google-ads/api/docs/query/overview for GAQL syntax.
- **google_ads_keyword_volume** — Get historical search volume estimates for a list of keywords using the Google Ads Keyword Planner. Returns avg monthly searches, competition level, and CPC bid range for each keyword.
- **google_ads_list_experiments** — List all experiments in the account, optionally filtered by base campaign ID.
- **google_ads_get_experiment** — Get full details for an experiment including its arms and treatment campaign ID.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "google-ads": {
    "command": "npx",
    "args": ["-y","mcp-google-ads"],
    "env": {
      "GOOGLE_ADS_DEVELOPER_TOKEN": "",
      "GOOGLE_ADS_CLIENT_ID": "",
      "GOOGLE_ADS_CLIENT_SECRET": "",
      "GOOGLE_ADS_REFRESH_TOKEN": ""
    }
  }
}
```

**Requires environment variables:** `GOOGLE_ADS_DEVELOPER_TOKEN`, `GOOGLE_ADS_CLIENT_ID`, `GOOGLE_ADS_CLIENT_SECRET`, `GOOGLE_ADS_REFRESH_TOKEN` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What google-ads does

google-ads exposes Google Ads API operations through Model Context Protocol tools. It supports MCC configurations with several client accounts and can select the active account from the working directory. The toolset covers campaign and ad-group discovery, campaign tracking, conversion actions, keyword and ad reporting, search-term analysis, campaign diagnostics, ad-strength checks, keyword-volume estimates, experiments, and custom GAQL queries.

Reporting tools return advertising metrics such as impressions, clicks, cost, conversions, quality-score components, impression share, ad copy, final URLs, and ad-strength ratings. Conversion-focused variants break keyword, ad, or search-term performance down by conversion action. Search-term insight tools provide category-level data and can drill into individual terms.

## How it works

Configure one MCC account and map named client entries to Google Ads customer IDs and workspace folders. When an MCP client invokes `google_ads_get_client_context`, the server reports the account associated with the current working directory and its health status. Calling that tool first helps avoid operating against the wrong client account.

The server is read-only by default. Mutating tools remain hidden unless `GOOGLE_ADS_MCP_WRITE=true` is set in the server environment. New items are configured to start paused, and enabling approved items requires an approval step. RSA validation can run before creation and checks headline, description, URL, path, and label requirements. Retry and timeout handling use circuit-breaker behavior, while structured logs use Pino.

## Setup and configuration

Install the npm package with `npm install mcp-google-ads`, or clone the repository, install dependencies, and build it. The server requires a Google Ads developer token, an OAuth client ID, an OAuth client secret, and an OAuth refresh token. The Google Ads API must be enabled in the associated Google Cloud project.

Credentials can be placed in `config.json` or supplied through environment variables; environment variables take precedence. Configuration includes the OAuth scope, MCC customer ID, client-account mappings, workspace folders, paused-creation behavior, label prefixes, and approval requirements. The bundled refresh-token helper uses an installed-app OAuth flow with PKCE and requests the configured Google Ads scope. Keep MCP configuration files containing credentials out of source control.

Add the server as a Node-based MCP process in Claude Code settings. Claude Desktop can also load it from its platform-specific MCP configuration file.

## Tools and capabilities

- Identify the active client account and inspect account health.
- List campaigns, ad groups, pending labeled changes, conversion actions, experiments, and experiment details.
- Retrieve campaign tracking settings and campaign diagnostics.
- Report on keyword, ad, search-term, and conversion-action performance.
- Inspect search-term categories and drill into category terms.
- Check RSA ad strength and validate RSA inputs before creation.
- Estimate keyword volume, competition, and CPC bid ranges.
- Run raw Google Ads Query Language statements for resources and reports not covered by dedicated tools.

## Limitations and notes

GAQL queries require valid Google Ads Query Language syntax. Search-term insights operate on one campaign at a time, and drilling into insight terms requires an `insight_id` from the category-insights tool. The developer token is a separate credential from the OAuth scope. Enabling write access changes the available tool surface, so protect the server environment and review changes before making them live.

_Full upstream README: https://allmcps.com/mcp/google-ads-8/readme_