Docs · Updated 2026-10-05

Google Ads — tool reference

Read-only Google Ads reports using your own approved developer token and Google OAuth app. Needs your credentials; real-account acceptance remains unverified.

Server URL: https://toolcargo.com/mcp/google-ads · Scope: connector:google-ads. Included with Site Audit; each successful operation uses one shared plan call.

Bring your Google Ads credentials

Open Google Ads connection settings. Supply your developer token, Google OAuth client ID and client secret, and a refresh token issued for that client with https://www.googleapis.com/auth/adwords. Use credentials belonging to you or authorized for your account. Do not paste them into an assistant conversation or an MCP tool call.

Your developer token must have an access level that permits the account you query. Test-account access works only with Google Ads test accounts. ToolCargo's own developer token is pending; BYO supplies a separate token. See Google's developer-token guide and OAuth and HTTP header reference.

Authorize your own OAuth app using Google's Google Ads OAuth instructions. If you use OAuth Playground, select your own client credentials and the adwords scope; an unrelated Playground refresh token will not belong to your client. Testing-mode refresh grants may expire after seven days. Your OAuth app verification, test-user list and developer-token approval are your responsibility; ToolCargo does not create apps or change your existing Google connection.

If you query a client account through a manager, enter the manager's ten-digit login customer ID. The report's customer_id is the client account to report on. A direct account user usually does not need the manager field. Accessible-account listing returns direct access only, without walking the manager hierarchy.

Credential storage and permissions

Credentials are encrypted and bound to your ToolCargo account and this connector. Connecting verifies them by exchanging the refresh token at oauth2.googleapis.com/token, then listing accessible customers at googleads.googleapis.com. Each tool refreshes access without caching the access token. Disconnect deletes the stored credential; revoke the grant in Google if you need to invalidate it there.

Google's adwords OAuth scope itself permits broad account operations. ToolCargo exposes only fixed account-list and curated reporting requests; no user-provided GAQL, arbitrary URLs, create, update, pause, budget or billing operations are accepted. Requests go directly to Google's official APIs. API v25 is pinned.

google_ads_list_accounts

List up to 100 Google Ads customer IDs directly accessible with your connected OAuth credentials. Manager descendants are not automatically enumerated.

google_ads_list_campaigns

Read up to 100 campaigns in one customer: ID, name, status and channel, with currency and account timezone. Optional campaign ID filter. No changes.

google_ads_list_ad_groups

Read up to 100 ad groups and their campaigns in one customer. Optional numeric campaign or ad group filters. Read-only.

google_ads_keyword_report

Keyword metrics by date range: impressions, clicks, cost, conversions and conversion value; keyword text and match type. Up to 100 top rows by cost, optional daily segmentation and campaign/ad group filters.

google_ads_search_terms

Read up to 100 highest-cost reported search terms over explicit dates, with campaigns, ad groups and metrics. Google privacy thresholds mean this is not a complete query log. No negative keywords are created.

google_ads_performance

Read campaign performance over explicit inclusive dates (at most 366 days or 93 when daily). Metrics remain decimal strings; cost and CPC are in micros of the account currency, CTR is a ratio. Up to 100 rows.

Inputs

list campaigns

{ "customer_id": "123-456-7890", "limit": 25 }

dated campaign performance

{ "customer_id": "1234567890", "since": "2026-09-01", "until": "2026-09-30", "daily": true, "limit": 50 }

search terms in one campaign

{ "customer_id": "1234567890", "campaign_id": "123456789", "since": "2026-09-01", "until": "2026-09-30", "limit": 100 }

Report coverage and units

Dates are inclusive, interpreted by Google in the account timezone. Maximum range: 366 days, or 93 when daily: true. Lists and reports have 1–100 rows per call; account discovery returns up to 100 of at most 1,000 directly accessible accounts. Reports use a fixed GAQL LIMIT, ordered by cost (or date then cost for daily rows). This is a bounded top-row report, not a complete export. Narrow by dates, campaign or ad group to focus on another slice; no automatic pagination is performed.

costMicros and averageCpcMicros are millionths of the account currency; divide by 1,000,000 for currency units. ctrRatio is a ratio; multiply by 100 for percent. IDs and numeric metrics remain strings to preserve source precision. Missing metrics are null, rather than invented zeros.

Search-term privacy thresholds hide some queries. Keyword reports cover keyword-view records, not all targeting methods. Conversion attribution, adjustments and reporting delays apply; recent dates can be incomplete. Empty results do not prove no spending or conversions occurred. A successful account-list check does not establish access to every client account.

Acceptance status

Real Google Ads account acceptance is pending credentials with a suitable developer-token access level and OAuth grant. Deterministic API tests and live tools/list confirm the adapter and transport; they do not prove access to your account. Named-client acceptance is separate. This is an original ToolCargo adapter, not an official Google product.

Set up Google Ads

Review connection instructions, required credentials and plan limits before connecting your agent.

View setup instructions