get_google_ads_report

Instructions

Implementation Reference

• src/ads_mcp_server/server.py:72-113 (handler)

  The main handler function `get_google_ads_report_impl` that executes the tool logic. Validates inputs, fetches/loads Google Ads data (56-day performance, settings, changes), and builds the response via `aggregate.build_response`.

  def get_google_ads_report_impl(
      date_range: str, breakdown: str, include_campaign_settings: bool = False
  ) -> dict[str, Any]:
      if date_range not in VALID_RANGES:
          return error_response("google", f"Invalid date_range. Use one of {VALID_RANGES}")
      if breakdown not in ("account", "campaign_type", "ad"):
          return error_response("google", f"Invalid breakdown: {breakdown}")
      app = get_app_config()
      if not app.google.is_configured:
          return error_response(
              "google",
              "Missing Google Ads credentials",
              missing_keys=app.google.missing,
          )
      try:
          today = _today()
          df_56d, source = _ensure_google_56d(app)
          settings = cache.load_settings_cache("google", today)
          if settings is None:
              settings = google_ads.fetch_settings(app.google)
              cache.save_settings_cache("google", settings)
          settings = _settings_with_types(settings, google_classifier())
          changes = cache.load_changes_cache("google", today)
          if changes is None:
              changes = google_ads.fetch_changes(app.google, today)
              cache.save_changes_cache("google", changes)
          return aggregate.build_response(
              df_56d=df_56d,
              settings=settings,
              date_range=date_range,
              breakdown=breakdown,
              today=_today(),
              thresholds=app.thresholds,
              platform="google",
              fetched_at=_now_iso(),
              data_source=source,
              change_history=changes,
              include_campaign_settings=include_campaign_settings,
          )
      except Exception as e:
          log.exception("Google tool failed")
          return error_response("google", str(e))

• src/ads_mcp_server/server.py:207-240 (registration)

  Tool registration via MCP `Tool` object with name 'get_google_ads_report', description, and inputSchema (date_range, breakdown, include_campaign_settings).

  Tool(
      name="get_google_ads_report",
      description=(
          "Pull Google Ads performance. Returns account totals, "
          "campaign-type breakdown, top-50 per-ad rows with diagnosis, "
          "56-day daily series, and WoW + 8-week DoW comparisons. "
          "Set include_campaign_settings=True to also return per-campaign "
          "settings (target CPA, daily budget, diagnosis, utilization) "
          "for ENABLED campaigns only."
      ),
      inputSchema={
          "type": "object",
          "properties": {
              "date_range": {
                  "type": "string",
                  "enum": list(VALID_RANGES),
              },
              "breakdown": {
                  "type": "string",
                  "enum": ["account", "campaign_type", "ad"],
              },
              "include_campaign_settings": {
                  "type": "boolean",
                  "default": False,
                  "description": (
                      "If true, attach campaign_settings list to "
                      "the response. Defaults to false to keep "
                      "payload small."
                  ),
              },
          },
          "required": ["date_range", "breakdown"],
      },
  ),

• src/ads_mcp_server/server.py:282-287 (registration)

  Tool dispatch in `call_tool`: routes the name 'get_google_ads_report' to call `get_google_ads_report_impl` with parsed arguments.

  if name == "get_google_ads_report":
      result = get_google_ads_report_impl(
          arguments["date_range"],
          arguments["breakdown"],
          include_campaign_settings=bool(arguments.get("include_campaign_settings", False)),
      )

• src/ads_mcp_server/server.py:217-239 (schema)

  Input schema for the tool: defines date_range (enum), breakdown (enum: account/campaign_type/ad), and optional include_campaign_settings boolean.

  inputSchema={
      "type": "object",
      "properties": {
          "date_range": {
              "type": "string",
              "enum": list(VALID_RANGES),
          },
          "breakdown": {
              "type": "string",
              "enum": ["account", "campaign_type", "ad"],
          },
          "include_campaign_settings": {
              "type": "boolean",
              "default": False,
              "description": (
                  "If true, attach campaign_settings list to "
                  "the response. Defaults to false to keep "
                  "payload small."
              ),
          },
      },
      "required": ["date_range", "breakdown"],
  },