google_ads_list_ads

List Google Ads

Google

Description

List ads for a Google Ads account. Supports filtering by ad group, status, search, and pagination. Results are cached; pass refresh=true for latest data.

Read-onlyOpen-world

Usage

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "google_ads_list_ads",
    "arguments": {
      "customer_id": "1234567890",
      "reason": "List ads"
    }
  }
}
hopkin google ads list
FlagTypeRequiredDescription
--customer-idstringRequiredThe Google Ads Customer ID (10 digits, with or without dashes)
--login-customer-idstringOptionalMCC (Manager) Customer ID; required for managed accounts
--ad-group-idstringOptionalFilter by ad group ID (optional)
--adstringOptionalGet a specific ad by ID. When provided, returns only that ad and ignores other filters/pagination.
--ad-idsarrayOptionalGet multiple ads by ID. Mutually exclusive with ad_id. When provided, ignores other filters/pagination.
--searchstringOptionalSearch ads by name (case-insensitive partial match)
--statusarrayOptionalFilter by ad status: ENABLED, PAUSED, REMOVED
--limitintegerOptionalNumber of ads per page (default: 20, max: 100)
--cursorstringOptionalPagination cursor from previous response
--refreshbooleanOptionalForce fresh data from Google Ads API instead of using cache. Defaults to false (cache-first). Only set to true when you need real-time data.
 
{
  "mcpServers": {
    "google-ads": {
      "url": "https://mcp.hopkin.ai/google-ads/mcp",
      "transport": "sse"
    }
  }
}
  • List all
  • Filter by ad group
  • Get by ID
  • Search
  • Get multiple by ID
  • Filter by status

Parameters

NameTypeRequiredDescription
customer_id string Required The Google Ads Customer ID (10 digits, with or without dashes)pattern: ^[\d-]+$
reason string Required Why this tool call is neededminLength: 1, maxLength: 500
Optional parameters (9)
NameTypeRequiredDescription
login_customer_id string Optional MCC (Manager) Customer ID; required for managed accountspattern: ^[\d-]+$
ad_group_id string Optional Filter by ad group ID (optional)pattern: ^\d+$
ad_id string Optional Get a specific ad by ID. When provided, returns only that ad and ignores other filters/pagination.pattern: ^\d+$
ad_ids array Optional Get multiple ads by ID. Mutually exclusive with ad_id. When provided, ignores other filters/pagination.
search string Optional Search ads by name (case-insensitive partial match)minLength: 1
status array Optional Filter by ad status: ENABLED, PAUSED, REMOVED
limit integer Optional Number of ads per page (default: 20, max: 100)min: 1, max: 100
cursor string Optional Pagination cursor from previous responseminLength: 1
refresh boolean Optional Force fresh data from Google Ads API instead of using cache. Defaults to false (cache-first). Only set to true when you need real-time data.

Examples

List all

{
  "customer_id": "1234567890",
  "reason": "List ads"
}

hopkin google ads list --customer-id 1234567890

Filter by ad group

{
  "customer_id": "1234567890",
  "ad_group_id": "5555555555",
  "reason": "List ads in ad group"
}

hopkin google ads list --customer-id 1234567890 --ad-group-id 5555555555

Get by ID

{
  "customer_id": "1234567890",
  "ad_id": "7777777777",
  "reason": "Get ad details"
}

hopkin google ads list --customer-id 1234567890 --ad 7777777777

Search

{
  "customer_id": "1234567890",
  "search": "promo",
  "reason": "Find promo ads"
}

hopkin google ads list --customer-id 1234567890 --search promo

Get multiple by ID

{
  "customer_id": "1234567890",
  "ad_ids": [
    "111",
    "222",
    "333"
  ],
  "reason": "Get details for specific ads"
}

hopkin google ads list --customer-id 1234567890 --ad-ids 111,222,333

Filter by status

{
  "customer_id": "1234567890",
  "status": [
    "ENABLED"
  ],
  "reason": "List enabled ads"
}

hopkin google ads list --customer-id 1234567890 --status ENABLED