Research & Benchmarks Optimization AI Ads Analytics Why Madgicx? About Us Blog Careers Case Studies Events Glossary Guides Answers Pricing Login Try for Free
MCP docs menu

Google Ads MCP Insights Tools

Retrieve Google Ads performance metrics at customer, campaign, ad group, or ad level.

Tools for retrieving Google Ads performance metrics. The get_insights tool supports four reporting levels (customer, campaign, ad group, ad), a configurable metric list, and optional segment breakdowns.

get_insights

Retrieve Google Ads performance metrics at a chosen reporting level. Requires a date range. Returns the requested metrics with optional segment breakdowns. Values stored in micros (cost, average CPC, average CPM) are also returned converted to the account's currency.

Parameters

Parameter Type Description
customer_id string Google Ads customer ID. Accepts dashed (123-456-7890) or digits-only (1234567890) format. Required.
login_customer_id string | undefined Manager (MCC) customer ID for the login-customer-id header.
level "customer" | "campaign" | "ad_group" | "ad" Reporting level. Maps to the GAQL FROM clause. Use "customer" for account totals; "campaign", "ad_group", or "ad" for per-entity rows. Default: "customer".
date_range { start_date: string, end_date: string } Inclusive date range, YYYY-MM-DD. Required.
metrics InsightMetric[] Subset of metrics.* fields to include. Default: impressions, clicks, cost_micros, conversions, conversions_value, ctr, average_cpc. Only request what you need, because extra metrics inflate the query.
segments InsightSegment[] | undefined Optional segments.* breakdowns. Each segment multiplies rows (e.g., "date" gives one row per day).
campaign_ids string[] | undefined Optional campaign IDs to restrict results. Valid at any level.
ad_group_ids string[] | undefined Optional ad group IDs. Valid at levels "ad_group" and "ad".
ad_ids string[] | undefined Optional ad IDs. Valid only at level "ad".
order_by_metric InsightMetric | undefined Optional metric to ORDER BY. Must also appear in metrics.
order_desc boolean When ordering, sort descending. Default: true.
page_token string | undefined Pagination token from a previous response.
limit number | undefined Optional row cap (applied in GAQL).

Supported metrics

Pass any subset as metrics:

impressions, clicks, cost_micros, conversions, conversions_value, ctr, average_cpc, average_cpm, all_conversions, all_conversions_value, view_through_conversions, video_views, engagements

Supported segments

Pass any subset as segments to break down rows:

date, device, day_of_week, ad_network_type, click_type, geo_target_country, hour, month, week, quarter, year

Filter / level rules

  • ad_group_ids is only valid at level ad_group or ad
  • ad_ids is only valid at level ad
  • order_by_metric must also appear in the metrics list

Examples

Natural Language

What's my Google Ads spend and conversions for the last 30 days?
Top 10 campaigns by ROAS in customer 123-456-7890 last month
Daily impressions and clicks per device for campaign 22334455 in November

Account totals

{
  "tool": "get_insights",
  "arguments": {
    "customer_id": "123-456-7890",
    "level": "customer",
    "date_range": {
      "start_date": "2026-04-01",
      "end_date": "2026-04-30"
    },
    "metrics": ["impressions", "clicks", "cost_micros", "conversions"]
  }
}

Per-campaign breakdown

{
  "tool": "get_insights",
  "arguments": {
    "customer_id": "123-456-7890",
    "level": "campaign",
    "date_range": {
      "start_date": "2026-04-01",
      "end_date": "2026-04-30"
    },
    "metrics": ["cost_micros", "conversions", "conversions_value"],
    "order_by_metric": "conversions_value",
    "order_desc": true,
    "limit": 10
  }
}

Daily ad-group device breakdown

{
  "tool": "get_insights",
  "arguments": {
    "customer_id": "123-456-7890",
    "level": "ad_group",
    "date_range": {
      "start_date": "2026-04-01",
      "end_date": "2026-04-07"
    },
    "metrics": ["impressions", "clicks", "ctr"],
    "segments": ["date", "device"],
    "campaign_ids": ["22334455"]
  }
}

Response

Returns a list of metric rows. Cost-related fields are returned both as micros (raw API value) and as the account's currency (converted). Segments selected via segments appear as additional fields on each row.

Official Meta Business Partner

Connect your AI assistant to your ad accounts. The 7-day free trial includes both MCPs.

Sign in with your Madgicx login, add the server addresses and ask in plain words. Meta changes wait for your confirmation, and the Google Ads MCP only reads.

Try for Free ($0 Trial)
200,000+ advertisers
$10B+ annual ad spend visibility
4.6 / 5 on G2, from 220+ reviews