Google Ads

This connector reads the Google Ads API (googleads.googleapis.com, v25) with Google Ads Query Language (GAQL): accounts and manager (MCC) hierarchies, campaigns, ad groups, ads, keywords, search terms, budgets and impression share, conversion actions, change history and recommendations. 17 tools, all read-only.

Start with gads_playbook. It costs no API call and maps common questions (account health, wasted spend, negative keywords, Quality Score, budget pacing, period comparison, tracking audit, Performance Max, MCC roll-ups) to the right tools and tested GAQL queries.

Setup (one-time, about 15 minutes)

1. Open https://console.cloud.google.com, pick or create a project, then APIs & Services → Library → enable Google Ads API.
2. Open the Google Ads API page of that project and check its access level. Since 9 September 2026 access is granted to the Cloud project: no developer token and no manager account are needed. A new project starts at Test access, which only reaches test accounts (production accounts answer CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION). Request Explorer access (production accounts, 2,880 operations a day, often approved automatically) or Basic access (15,000 a day, needs brand verification of the project).
3. APIs & Services → OAuth consent screen: Internal on Google Workspace, otherwise External with publishing status In production. While an app is in Testing, Google revokes its refresh tokens after 7 days.
4. Credentials → Create credentials → OAuth client ID → Web application → authorized redirect URI <your AnythingMCP URL>/api/mcp-oauth/callback (on AnythingMCP Cloud: https://cloud.anythingmcp.com/api/mcp-oauth/callback).
5. Paste the client ID and secret into GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET. If you reach client accounts through a manager account, also set GOOGLE_ADS_LOGIN_CUSTOMER_ID to the manager's 10-digit id; leave it empty for accounts you were invited to directly.
6. On the connector page click Authorize with Provider and sign in with a Google user that has access to the Google Ads accounts. The refresh token is stored encrypted.

Permissions: Google Ads has a single OAuth scope (adwords) and it is not read-only, but this connector only exposes read tools. What the agent can see is what the signing-in user can see; a Google Ads user with the Read only role is the safest choice.

Accounts (customer_id)

• Always 10 digits without dashes. gads_list_accessible_customers lists accounts the user can open directly; gads_list_client_accounts on a manager id lists the accounts below it.
• A manager account holds no campaigns: querying campaigns on a manager id returns nothing or an error. Query its client accounts.
• USER_PERMISSION_DENIED on a client account usually means GOOGLE_ADS_LOGIN_CUSTOMER_ID is missing or is not a manager above that account.

Reading the numbers

• Money is in micros of the account currency: cost_micros 12500000 = 12.50. Divide by 1,000,000 and name the currency from gads_get_customer. average_cpc and cost_per_conversion are micros too.
• 64-bit numbers (ids, impressions, clicks, cost_micros) arrive as JSON strings. ctr and impression shares are fractions (0.034 = 3.4%).
• Dates are YYYY-MM-DD in the account's time zone. Report tools need start_date and end_date; compute them from today. Today's data is partial and conversions keep arriving for days after a click, so the last 2-3 days understate conversions.
• Report tools can return campaigns, ad groups or ads with zero metrics (paused, or idle in the range); they sort last, so skip them when summarising. Keyword and search-term reports only return rows with impressions. Results are capped by limit; if you get exactly limit rows, there are probably more.

GAQL (gads_run_gaql): SELECT fields FROM resource WHERE … ORDER BY … LIMIT n. Conditions combine with AND only (no OR; use IN). LIKE is case-sensitive; REGEXP_MATCH takes RE2 ('(?i)brand'). Relative ranges: segments.date DURING LAST_30_DAYS (also LAST_7_DAYS, LAST_14_DAYS, LAST_MONTH, THIS_MONTH, YESTERDAY, TODAY). A field used in WHERE on segments.* other than date must also be selected. Not every field combines with every resource: when the API says a field is incompatible, check it with gads_query_field_catalog.

Errors: CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION = the Cloud project still has Test access (step 2). RESOURCE_EXHAUSTED = daily or per-minute quota of the Cloud project, which every connector sharing that project draws from. UNRECOGNIZED_FIELD / PROHIBITED_* = a GAQL field name or combination problem. CUSTOMER_NOT_ENABLED = the account is cancelled or not yet set up. 401 = authorize again from the connector page.