Claude-skill-registry google-ads-mcp-navigator

Streamlined guide for Google Ads API queries via MCP. Use when querying campaign performance, keyword metrics, conversion data, auction insights, or ad group analysis. Reduces context overhead by providing curated field references and common query patterns. Triggers on Google Ads, SEM performance, campaign analysis, keyword research, or auction insights requests.

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/google-ads-mcp-navigator" ~/.claude/skills/majiayu000-claude-skill-registry-google-ads-mcp-navigator && rm -rf "$T"

manifest: skills/data/google-ads-mcp-navigator/SKILL.md

source content

Google Ads MCP Navigator

This skill provides efficient navigation of the Google Ads MCP tool, reducing context overhead by documenting common query patterns, curated field lists, and RDC-specific account configurations.

Quick Reference

RDC Account IDs

Account	Customer ID	Vertical	Notes
RDC SEM Main	see accessible_customers	Buy/Mixed	Primary B2C search
RDC Rentals	see accessible_customers	Rent	Rentals vertical
RDC Seller	see accessible_customers	Sell	Seller marketplace
RDC New Construction	see accessible_customers	NC	Builder campaigns

Run

list_accessible_customers

to get current account IDs

Core Resources

Resource	Use Case	Key Metrics Available
`campaign`	Campaign settings, status, budget	bidding strategy, status, dates
`ad_group`	Ad group settings, bids	CPC bids, status, targeting
`ad_group_ad`	Ad creative, approval status	ad strength, policy status
`ad_group_criterion`	Keywords, audiences	quality score, bids
`search_term_view`	Search query data	search terms, match type
`keyword_view`	Keyword performance	joins with metrics
`geographic_view`	Geo performance	location type
`campaign_budget`	Budget settings	amount, delivery method

Metrics Resource

All performance metrics come from the

metrics

resource and must be joined with a primary resource.

Workflow

Identify the analysis type:
- Campaign performance →
```
campaign
```
  +
```
metrics
```
- Keyword analysis →
```
ad_group_criterion
```
  or
```
keyword_view
```
  +
```
metrics
```
- Search query mining →
```
search_term_view
```
  +
```
metrics
```
- Auction insights →
```
auction_insight
```
  resource (special)
- Geographic performance →
```
geographic_view
```
  +
```
metrics
```
Load field references:
- Campaign fields → references/campaign_fields.md
- Metrics fields → references/metrics_fields.md
- Segment fields → references/segment_fields.md
Apply required conditions:
- Always filter by date range (required for metrics)
- Filter by campaign status for active-only analysis
- Use segments for dimensional breakdowns

Essential Field Lists

Campaign Performance (Minimal)

Fields: campaign.id, campaign.name, campaign.status, campaign.advertising_channel_type, 
        metrics.impressions, metrics.clicks, metrics.cost_micros, metrics.conversions, 
        metrics.conversions_value
Resource: campaign
Conditions: segments.date BETWEEN 'YYYY-MM-DD' AND 'YYYY-MM-DD'

Keyword Performance (Minimal)

Fields: ad_group.name, ad_group_criterion.keyword.text, ad_group_criterion.keyword.match_type,
        ad_group_criterion.quality_info.quality_score, metrics.impressions, metrics.clicks,
        metrics.cost_micros, metrics.conversions
Resource: ad_group_criterion
Conditions: ad_group_criterion.type = 'KEYWORD', segments.date BETWEEN 'YYYY-MM-DD' AND 'YYYY-MM-DD'

Search Terms (Minimal)

Fields: search_term_view.search_term, search_term_view.status, 
        metrics.impressions, metrics.clicks, metrics.cost_micros, metrics.conversions
Resource: search_term_view
Conditions: segments.date BETWEEN 'YYYY-MM-DD' AND 'YYYY-MM-DD'

Geographic Performance (Minimal)

Fields: geographic_view.location_type, segments.geo_target_region,
        metrics.impressions, metrics.clicks, metrics.cost_micros, metrics.conversions
Resource: geographic_view
Conditions: segments.date BETWEEN 'YYYY-MM-DD' AND 'YYYY-MM-DD'

Common Query Patterns

Campaign Summary (Last 30 Days)

resource: "campaign"
fields: [
    "campaign.id",
    "campaign.name", 
    "campaign.status",
    "campaign.advertising_channel_type",
    "campaign.bidding_strategy_type",
    "metrics.impressions",
    "metrics.clicks",
    "metrics.cost_micros",
    "metrics.conversions",
    "metrics.conversions_value",
    "metrics.search_impression_share"
]
conditions: [
    "segments.date >= 'YYYY-MM-DD'",
    "segments.date <= 'YYYY-MM-DD'",
    "campaign.status = 'ENABLED'"
]

Keyword Quality Score Analysis

resource: "ad_group_criterion"
fields: [
    "campaign.name",
    "ad_group.name",
    "ad_group_criterion.keyword.text",
    "ad_group_criterion.keyword.match_type",
    "ad_group_criterion.quality_info.quality_score",
    "ad_group_criterion.quality_info.creative_quality_score",
    "ad_group_criterion.quality_info.post_click_quality_score",
    "ad_group_criterion.quality_info.search_predicted_ctr",
    "metrics.impressions",
    "metrics.clicks",
    "metrics.cost_micros"
]
conditions: [
    "ad_group_criterion.type = 'KEYWORD'",
    "ad_group_criterion.status = 'ENABLED'",
    "segments.date >= 'YYYY-MM-DD'",
    "segments.date <= 'YYYY-MM-DD'"
]

Search Query Mining

resource: "search_term_view"
fields: [
    "campaign.name",
    "ad_group.name",
    "search_term_view.search_term",
    "search_term_view.status",
    "metrics.impressions",
    "metrics.clicks",
    "metrics.cost_micros",
    "metrics.conversions",
    "metrics.conversions_value"
]
conditions: [
    "segments.date >= 'YYYY-MM-DD'",
    "segments.date <= 'YYYY-MM-DD'",
    "metrics.impressions > 0"
]
orderings: ["metrics.cost_micros DESC"]
limit: 1000

Daily Performance Trend

resource: "campaign"
fields: [
    "segments.date",
    "campaign.name",
    "metrics.impressions",
    "metrics.clicks",
    "metrics.cost_micros",
    "metrics.conversions"
]
conditions: [
    "segments.date >= 'YYYY-MM-DD'",
    "segments.date <= 'YYYY-MM-DD'",
    "campaign.status = 'ENABLED'"
]
orderings: ["segments.date ASC"]

Device Performance

resource: "campaign"
fields: [
    "campaign.name",
    "segments.device",
    "metrics.impressions",
    "metrics.clicks",
    "metrics.cost_micros",
    "metrics.conversions"
]
conditions: [
    "segments.date >= 'YYYY-MM-DD'",
    "segments.date <= 'YYYY-MM-DD'"
]

Hour of Day Analysis

resource: "campaign"
fields: [
    "campaign.name",
    "segments.hour",
    "metrics.impressions",
    "metrics.clicks",
    "metrics.cost_micros",
    "metrics.conversions"
]
conditions: [
    "segments.date >= 'YYYY-MM-DD'",
    "segments.date <= 'YYYY-MM-DD'"
]

Metric Calculations

Derived Metrics (Calculate Post-Query)

Metric	Calculation
Cost	`cost_micros / 1,000,000`
CPC	`cost_micros / clicks / 1,000,000`
CTR	`clicks / impressions`
Conv Rate	`conversions / clicks`
CPA	`cost_micros / conversions / 1,000,000`
ROAS	`conversions_value / (cost_micros / 1,000,000)`

Impression Share Metrics

```
search_impression_share
```
- % of eligible impressions received
```
search_budget_lost_impression_share
```
- Lost due to budget
```
search_rank_lost_impression_share
```
- Lost due to rank
```
search_absolute_top_impression_share
```
- % in position 1

Date Handling

Critical: The Google Ads API requires explicit date formatting.

Format:
```
YYYY-MM-DD
```
(e.g.,
```
2024-12-01
```
)
Always use explicit dates, not literals like
```
TODAY
```
or
```
LAST_30_DAYS
```
Date conditions use
```
segments.date
```

Date Range Examples

# Last 7 days (calculate actual dates)
conditions: [
    "segments.date >= '2024-12-10'",
    "segments.date <= '2024-12-17'"
]

# Specific month
conditions: [
    "segments.date >= '2024-11-01'",
    "segments.date <= '2024-11-30'"
]

Status Values

Campaign Status

```
ENABLED
```
- Active
```
PAUSED
```
- Paused by user
```
REMOVED
```
- Deleted

Ad Group Criterion Status

```
ENABLED
```
- Active keyword
```
PAUSED
```
- Paused keyword
```
REMOVED
```
- Deleted keyword

Search Term Status

```
ADDED
```
- Added as keyword
```
EXCLUDED
```
- Added as negative
```
ADDED_EXCLUDED
```
- Both
```
NONE
```
- Not actioned

Channel Types

Integration with Snowflake

Cross-reference Google Ads data with RDC Snowflake tables:

Google Ads Field	Snowflake Field	Table
`campaign.id`	`campaign_id`	`sem_summary`
`campaign.name`	`campaign_name`	`sem_summary`
N/A (calculated)	`google_click_id`	`clickstream_detail`

Joining Pattern

Query Google Ads for campaign IDs, then use in Snowflake:

SELECT * FROM rdc_marketing.agg_reporting.sem_summary
WHERE campaign_id IN (12345, 67890)  -- From Google Ads query
  AND event_date >= DATEADD('day', -30, CURRENT_DATE());

Auction Insights

Auction Insights provides competitive intelligence showing how your ads perform against other advertisers in the same auctions. Available for Search and Shopping campaigns only.

Key Segment

```
segments.auction_insight_domain
```
- Returns competitor domain names (required for auction insights)

Auction Insight Metrics

Metric	Description
`metrics.auction_insight_search_impression_share`	% of impressions you received vs. total eligible
`metrics.auction_insight_search_overlap_rate`	How often competitor showed alongside you
`metrics.auction_insight_search_position_above_rate`	How often competitor ranked above you
`metrics.auction_insight_search_top_impression_percentage`	% of impressions at top of page
`metrics.auction_insight_search_absolute_top_impression_percentage`	% of impressions in position #1
`metrics.auction_insight_search_outranking_share`	% of auctions where you outranked competitor

Campaign-Level Auction Insights

resource: "campaign"
fields: [
    "campaign.id",
    "campaign.name",
    "segments.auction_insight_domain",
    "metrics.auction_insight_search_impression_share",
    "metrics.auction_insight_search_overlap_rate",
    "metrics.auction_insight_search_position_above_rate",
    "metrics.auction_insight_search_top_impression_percentage",
    "metrics.auction_insight_search_absolute_top_impression_percentage",
    "metrics.auction_insight_search_outranking_share"
]
conditions: [
    "campaign.status = 'ENABLED'",
    "segments.date >= 'YYYY-MM-DD'",
    "segments.date <= 'YYYY-MM-DD'"
]

Keyword-Level Auction Insights

resource: "ad_group_criterion"
fields: [
    "campaign.name",
    "ad_group.name",
    "ad_group_criterion.keyword.text",
    "segments.auction_insight_domain",
    "metrics.auction_insight_search_impression_share",
    "metrics.auction_insight_search_overlap_rate",
    "metrics.auction_insight_search_position_above_rate"
]
conditions: [
    "ad_group_criterion.type = 'KEYWORD'",
    "ad_group_criterion.status = 'ENABLED'",
    "segments.date >= 'YYYY-MM-DD'",
    "segments.date <= 'YYYY-MM-DD'"
]

Interpreting Results

Treat Analysis as Relative to historical performance: rather than relying on a hard threshold, develop an understanding of previous behavior vs. current behavior, and interpret the difference. When there is no previous behavior to compare, use the following rules.
High overlap rate (>50%): Frequent direct competition
Position above rate >50%: Competitor usually beats you
Outranking share: Combines position wins + showing when they didn't
Results include your own domain as benchmark

See references/auction_insights.md for comprehensive guidance.

Reference Documents

campaign_fields.md - All campaign resource fields
metrics_fields.md - All metrics fields with descriptions
segment_fields.md - All segmentation options
keyword_fields.md - Keyword and criterion fields
auction_insights.md - Competitive analysis and auction insights

Tips for Efficient Queries

Minimize fields - Only request fields you need
Use limits - Add
```
limit
```
for exploratory queries
Filter early - Use conditions to reduce data volume
Segment wisely - Each segment dimension multiplies rows
Check status - Filter to ENABLED for active items only
Date ranges - Shorter ranges = faster queries
Batch accounts - Query one customer_id at a time