google_ads_recommendations

Instructions

Implementation Reference

• google_ads_mcp.py:410-473 (handler)

  Handler function that queries Google Ads recommendations via GAQL, filters by type, and returns formatted results in markdown or JSON.

  @mcp.tool()
  def google_ads_recommendations(
      customer_id: str,
      recommendation_types: Optional[List[str]] = None,
      limit: int = 20,
      response_format: str = "markdown",
  ) -> str:
      """
      Get AI-powered optimization recommendations from Google.
  
      Retrieve Google's automated recommendations for improving campaign performance,
      including keyword suggestions, bid adjustments, and budget recommendations.
  
      Args:
          customer_id: Customer ID without hyphens
          recommendation_types: Filter by recommendation types
              (e.g., ['KEYWORD', 'TARGET_CPA_OPT'])
          limit: Maximum number of recommendations (1-100)
          response_format: Output format: 'markdown' or 'json'
  
      Returns:
          List of actionable optimization recommendations
      """
      try:
          client = get_auth_manager().get_client()
          ga_service = client.get_service("GoogleAdsService")
          clean_id = customer_id.replace("-", "")
  
          query = (
              "SELECT recommendation.resource_name, recommendation.type, "
              "recommendation.impact, recommendation.campaign "
              "FROM recommendation "
              "WHERE recommendation.dismissed = FALSE"
          )
  
          if recommendation_types:
              types_str = ", ".join(f"'{t}'" for t in recommendation_types)
              query += f" AND recommendation.type IN ({types_str})"
  
          query += f" LIMIT {min(max(limit, 1), 100)}"
  
          response = ga_service.search(customer_id=clean_id, query=query)
  
          recs = []
          for row in response:
              recs.append({
                  "type": row.recommendation.type.name,
                  "campaign": row.recommendation.campaign or "Account-level",
                  "impact": str(row.recommendation.impact),
              })
  
          if response_format == "json":
              return json.dumps(recs, indent=2, default=str)
  
          out = f"# Optimization Recommendations\n\n"
          out += f"**Total**: {len(recs)}\n\n"
          out += "| Type | Campaign | Impact |\n"
          out += "|------|----------|--------|\n"
          for r in recs:
              out += f"| {r['type']} | {r['campaign'][:30]} | {r['impact'][:50]} |\n"
          return out
  
      except Exception as exc:
          return f"❌ Recommendations query failed: {exc}"

• google_ads_mcp.py:410-416 (registration)

  Registered as an MCP tool via the @mcp.tool() decorator on the FastMCP instance.

  @mcp.tool()
  def google_ads_recommendations(
      customer_id: str,
      recommendation_types: Optional[List[str]] = None,
      limit: int = 20,
      response_format: str = "markdown",
  ) -> str: