google_ads_search_terms

Instructions

Implementation Reference

• google_ads_mcp.py:329-407 (handler)

  The handler function for the 'google_ads_search_terms' tool. Executes a GAQL query on 'search_term_view' to retrieve actual search queries that triggered ads, with optional campaign_id filtering, and returns results as markdown or JSON.

  def google_ads_search_terms(
      customer_id: str,
      campaign_id: Optional[str] = None,
      date_range: str = "LAST_30_DAYS",
      limit: int = 100,
      response_format: str = "markdown",
  ) -> str:
      """
      View actual search queries that triggered your ads.
  
      Shows the search terms report with performance metrics to identify
      new keyword opportunities and negative keyword candidates.
  
      Args:
          customer_id: Customer ID without hyphens
          campaign_id: Optional campaign ID to filter
          date_range: Date range for the report
          limit: Maximum number of search terms to return
          response_format: Output format: 'markdown' or 'json'
  
      Returns:
          Search terms with performance metrics
      """
      try:
          client = get_auth_manager().get_client()
          ga_service = client.get_service("GoogleAdsService")
          clean_id = customer_id.replace("-", "")
  
          query = (
              "SELECT campaign.name, ad_group.name, "
              "search_term_view.search_term, search_term_view.status, "
              "metrics.impressions, metrics.clicks, metrics.cost_micros, "
              "metrics.conversions "
              f"FROM search_term_view WHERE segments.date DURING {date_range}"
          )
  
          if campaign_id:
              query += f" AND campaign.id = {campaign_id}"
  
          query += f" ORDER BY metrics.impressions DESC LIMIT {min(limit, 200)}"
  
          response = ga_service.search(customer_id=clean_id, query=query)
  
          terms = []
          for row in response:
              cost = row.metrics.cost_micros / 1_000_000
              imps = row.metrics.impressions
              clicks = row.metrics.clicks
              ctr = (clicks / imps * 100) if imps > 0 else 0
  
              terms.append({
                  "search_term": row.search_term_view.search_term,
                  "campaign": row.campaign.name,
                  "ad_group": row.ad_group.name,
                  "status": row.search_term_view.status.name,
                  "impressions": imps,
                  "clicks": clicks,
                  "ctr": round(ctr, 2),
                  "cost": round(cost, 2),
                  "conversions": round(row.metrics.conversions, 2),
              })
  
          if response_format == "json":
              return json.dumps(terms, indent=2)
  
          out = f"# Search Terms Report ({date_range})\n\n"
          out += f"**Total terms**: {len(terms)}\n\n"
          out += "| Search Term | Campaign | Impr | Clicks | CTR | Cost | Conv | Status |\n"
          out += "|-------------|----------|------|--------|-----|------|------|--------|\n"
          for t in terms:
              out += (
                  f"| {t['search_term'][:40]} | {t['campaign'][:20]} "
                  f"| {t['impressions']:,} | {t['clicks']:,} | {t['ctr']}% "
                  f"| ${t['cost']:.2f} | {t['conversions']:.1f} | {t['status']} |\n"
              )
          return out
  
      except Exception as exc:
          return f"❌ Search terms query failed: {exc}"

• google_ads_mcp.py:329-335 (schema)

  Function signature and docstring defining the input parameters/schema: customer_id (str), campaign_id (Optional[str]), date_range (str, default LAST_30_DAYS), limit (int, default 100), response_format (str, default markdown).

  def google_ads_search_terms(
      customer_id: str,
      campaign_id: Optional[str] = None,
      date_range: str = "LAST_30_DAYS",
      limit: int = 100,
      response_format: str = "markdown",
  ) -> str:

• google_ads_mcp.py:328-328 (registration)

  The tool is registered via the @mcp.tool() decorator on line 328, which is part of the FastMCP framework.

  @mcp.tool()