Can I use Google Ads as a CLI?

Yes. KosmoKrator exposes a Google Ads CLI through kosmo integrations:call and the provider shortcut command. Commands can return JSON for scripts, CI, and coding agents.

Can I expose Google Ads through MCP?

Yes. The KosmoKrator MCP gateway can expose selected Google Ads tools to clients such as Claude Code, Cursor, Codex, and other MCP-compatible tools.

Where are Google Ads credentials stored?

Google Ads credentials are configured in KosmoKrator's local integration settings and reused by CLI, Lua, and MCP gateway surfaces.

Can I deny write access for Google Ads MCP tools?

Yes. Start the gateway with --write=deny for read-only clients, or use ask/allow only for trusted workspaces.

analytics

Google Ads CLI for AI Agents

Use the Google Ads CLI from KosmoKrator to call Google Ads tools headlessly, return JSON, inspect schemas, and automate workflows from coding agents, scripts, and CI.

38 functions 18 read 20 write oauth2 with developer token auth

Submit Google Ads feedback View package source

Google Ads CLI Setup

Google Ads can be configured headlessly with `kosmokrator integrations:configure google_ads`.

# Install KosmoKrator first if it is not available on PATH.
curl -fsSL https://raw.githubusercontent.com/OpenCompanyApp/kosmokrator/main/install.sh | bash

# Configure and verify this integration.
kosmokrator integrations:configure google_ads --set developer_token="$GOOGLE_ADS_DEVELOPER_TOKEN" --enable --read allow --write ask --json
kosmokrator integrations:doctor google_ads --json
kosmokrator integrations:status --json

Runtime Requirements

Install these host dependencies before calling Google Ads locally.

Name	Type	Description
`runtime`	dependency
`runtime`	dependency
`runtime`	dependency

Credentials

Authentication type: oauth2 with developer token oauth2_with_developer_token. Configure credentials once, then use the same stored profile from scripts, coding CLIs, Lua code mode, and the MCP gateway.

Key	Env var	Type	Required	Label
`developer_token`	`GOOGLE_ADS_DEVELOPER_TOKEN`	Secret `secret`	yes	Developer Token
`access_token`	`GOOGLE_ADS_ACCESS_TOKEN`	Secret `secret`	no	Access Token
`refresh_token`	`GOOGLE_ADS_REFRESH_TOKEN`	Secret `secret`	no	Refresh Token
`client_id`	`GOOGLE_ADS_CLIENT_ID`	Text `string`	no	OAuth Client ID
`client_secret`	`GOOGLE_ADS_CLIENT_SECRET`	Secret `secret`	no	OAuth Client Secret
`manager_customer_id`	`GOOGLE_ADS_MANAGER_CUSTOMER_ID`	Text `string`	no	Manager Customer ID
`default_customer_id`	`GOOGLE_ADS_DEFAULT_CUSTOMER_ID`	Text `string`	no	Default Customer ID
`api_version`	`GOOGLE_ADS_API_VERSION`	Text `string`	no	API Version

Call Google Ads Headlessly

Use the generic call form when another coding CLI or script needs a stable universal interface.

kosmo integrations:call google_ads.google_ads_diagnostics '{}' --json

Use the provider shortcut form for shorter human-facing commands.

kosmo integrations:google_ads google_ads_diagnostics '{}' --json

Agent Discovery Commands

These commands return structured output for coding agents that need to inspect capabilities before choosing a function.

kosmo integrations:docs google_ads --json
kosmo integrations:docs google_ads.google_ads_diagnostics --json
kosmo integrations:schema google_ads.google_ads_diagnostics --json
kosmo integrations:search "Google Ads" --json
kosmo integrations:list --json

All CLI Functions

Every function below can be called headlessly. The generic form is stable across all integrations; the provider shortcut is shorter but specific to Google Ads.

`google_ads.google_ads_diagnostics`

Read read

Show safe configuration diagnostics.

Parameters: none

Generic CLI call

kosmo integrations:call google_ads.google_ads_diagnostics '{}' --json

Provider shortcut

kosmo integrations:google_ads google_ads_diagnostics '{}' --json

`google_ads.google_ads_list_accessible_customers`

Read read

List Google Ads customers directly accessible to the OAuth user.

Parameters: none

Generic CLI call

kosmo integrations:call google_ads.google_ads_list_accessible_customers '{}' --json

Provider shortcut

kosmo integrations:google_ads google_ads_list_accessible_customers '{}' --json

`google_ads.google_ads_list_customer_clients`

Read read

List managed client accounts under a manager or customer.

Parameters: none

Generic CLI call

kosmo integrations:call google_ads.google_ads_list_customer_clients '{}' --json

Provider shortcut

kosmo integrations:google_ads google_ads_list_customer_clients '{}' --json

`google_ads.google_ads_search`

Read read

Run a paginated Google Ads Query Language search.

Parameters: none

Generic CLI call

kosmo integrations:call google_ads.google_ads_search '{}' --json

Provider shortcut

kosmo integrations:google_ads google_ads_search '{}' --json

`google_ads.google_ads_search_stream`

Read read

Run a streaming GAQL report for larger result sets.

Parameters: none

Generic CLI call

kosmo integrations:call google_ads.google_ads_search_stream '{}' --json

Provider shortcut

kosmo integrations:google_ads google_ads_search_stream '{}' --json

`google_ads.google_ads_campaign_report`

Read read

Run a normalized campaign performance report.

Parameters: none

Generic CLI call

kosmo integrations:call google_ads.google_ads_campaign_report '{}' --json

Provider shortcut

kosmo integrations:google_ads google_ads_campaign_report '{}' --json

`google_ads.google_ads_ad_group_report`

Read read

Run a normalized ad group performance report.

Parameters: none

Generic CLI call

kosmo integrations:call google_ads.google_ads_ad_group_report '{}' --json

Provider shortcut

kosmo integrations:google_ads google_ads_ad_group_report '{}' --json

`google_ads.google_ads_ad_report`

Read read

Run an ad and creative performance report.

Parameters: none

Generic CLI call

kosmo integrations:call google_ads.google_ads_ad_report '{}' --json

Provider shortcut

kosmo integrations:google_ads google_ads_ad_report '{}' --json

`google_ads.google_ads_keyword_report`

Read read

Run a keyword performance report.

Parameters: none

Generic CLI call

kosmo integrations:call google_ads.google_ads_keyword_report '{}' --json

Provider shortcut

kosmo integrations:google_ads google_ads_keyword_report '{}' --json

`google_ads.google_ads_search_term_report`

Read read

Analyze search terms and query performance.

Parameters: none

Generic CLI call

kosmo integrations:call google_ads.google_ads_search_term_report '{}' --json

Provider shortcut

kosmo integrations:google_ads google_ads_search_term_report '{}' --json

`google_ads.google_ads_asset_report`

Read read

Report on assets and policy/performance labels.

Parameters: none

Generic CLI call

kosmo integrations:call google_ads.google_ads_asset_report '{}' --json

Provider shortcut

kosmo integrations:google_ads google_ads_asset_report '{}' --json

`google_ads.google_ads_performance_max_report`

Read read

Report on Performance Max campaigns and asset groups.

Parameters: none

Generic CLI call

kosmo integrations:call google_ads.google_ads_performance_max_report '{}' --json

Provider shortcut

kosmo integrations:google_ads google_ads_performance_max_report '{}' --json

`google_ads.google_ads_list_campaigns`

Read read

List campaigns with status, budget, channel, and optimization fields.

Parameters: none

Generic CLI call

kosmo integrations:call google_ads.google_ads_list_campaigns '{}' --json

Provider shortcut

kosmo integrations:google_ads google_ads_list_campaigns '{}' --json

`google_ads.google_ads_create_campaign_budget`

Write write

Create a campaign budget with micros normalization.

Parameters: none

Generic CLI call

kosmo integrations:call google_ads.google_ads_create_campaign_budget '{}' --json

Provider shortcut

kosmo integrations:google_ads google_ads_create_campaign_budget '{}' --json

`google_ads.google_ads_manage_campaign`

Write write

Create, update, pause, enable, or remove campaigns.

Parameters: none

Generic CLI call

kosmo integrations:call google_ads.google_ads_manage_campaign '{}' --json

Provider shortcut

kosmo integrations:google_ads google_ads_manage_campaign '{}' --json

`google_ads.google_ads_manage_ad_group`

Write write

Create, update, pause, enable, or remove ad groups.

Parameters: none

Generic CLI call

kosmo integrations:call google_ads.google_ads_manage_ad_group '{}' --json

Provider shortcut

kosmo integrations:google_ads google_ads_manage_ad_group '{}' --json

`google_ads.google_ads_manage_keyword`

Write write

Add, update, or remove keyword criteria.

Parameters: none

Generic CLI call

kosmo integrations:call google_ads.google_ads_manage_keyword '{}' --json

Provider shortcut

kosmo integrations:google_ads google_ads_manage_keyword '{}' --json

`google_ads.google_ads_manage_ad`

Write write

Create or manage responsive search ads and ad statuses.

Parameters: none

Generic CLI call

kosmo integrations:call google_ads.google_ads_manage_ad '{}' --json

Provider shortcut

kosmo integrations:google_ads google_ads_manage_ad '{}' --json

`google_ads.google_ads_manage_campaign_criteria`

Write write

Add or remove location, language, schedule, and negative criteria.

Parameters: none

Generic CLI call

kosmo integrations:call google_ads.google_ads_manage_campaign_criteria '{}' --json

Provider shortcut

kosmo integrations:google_ads google_ads_manage_campaign_criteria '{}' --json

`google_ads.google_ads_upload_image_asset`

Write write

Create image assets from pre-encoded image metadata.

Parameters: none

Generic CLI call

kosmo integrations:call google_ads.google_ads_upload_image_asset '{}' --json

Provider shortcut

kosmo integrations:google_ads google_ads_upload_image_asset '{}' --json

`google_ads.google_ads_link_asset`

Write write

Link an asset to a customer, campaign, ad group, or asset group.

Parameters: none

Generic CLI call

kosmo integrations:call google_ads.google_ads_link_asset '{}' --json

Provider shortcut

kosmo integrations:google_ads google_ads_link_asset '{}' --json

`google_ads.google_ads_create_search_campaign`

Write write

Create a complete paused Search campaign with budget, ad group, keywords, targets, and RSA.

Parameters: none

Generic CLI call

kosmo integrations:call google_ads.google_ads_create_search_campaign '{}' --json

Provider shortcut

kosmo integrations:google_ads google_ads_create_search_campaign '{}' --json

`google_ads.google_ads_create_performance_max_campaign`

Write write

Create a governed Performance Max campaign using mixed mutate operations.

Parameters: none

Generic CLI call

kosmo integrations:call google_ads.google_ads_create_performance_max_campaign '{}' --json

Provider shortcut

kosmo integrations:google_ads google_ads_create_performance_max_campaign '{}' --json

`google_ads.google_ads_generate_keyword_ideas`

Read read

Generate keyword ideas and forecasts inputs.

Parameters: none

Generic CLI call

kosmo integrations:call google_ads.google_ads_generate_keyword_ideas '{}' --json

Provider shortcut

kosmo integrations:google_ads google_ads_generate_keyword_ideas '{}' --json

`google_ads.google_ads_list_recommendations`

Read read

List optimization recommendations.

Parameters: none

Generic CLI call

kosmo integrations:call google_ads.google_ads_list_recommendations '{}' --json

Provider shortcut

kosmo integrations:google_ads google_ads_list_recommendations '{}' --json

`google_ads.google_ads_apply_recommendations`

Write write

Apply selected recommendations with explicit confirmation.

Parameters: none

Generic CLI call

kosmo integrations:call google_ads.google_ads_apply_recommendations '{}' --json

Provider shortcut

kosmo integrations:google_ads google_ads_apply_recommendations '{}' --json

`google_ads.google_ads_upload_click_conversions`

Write write

Upload offline or enhanced lead click conversions.

Parameters: none

Generic CLI call

kosmo integrations:call google_ads.google_ads_upload_click_conversions '{}' --json

Provider shortcut

kosmo integrations:google_ads google_ads_upload_click_conversions '{}' --json

`google_ads.google_ads_upload_call_conversions`

Write write

Upload offline call conversions.

Parameters: none

Generic CLI call

kosmo integrations:call google_ads.google_ads_upload_call_conversions '{}' --json

Provider shortcut

kosmo integrations:google_ads google_ads_upload_call_conversions '{}' --json

`google_ads.google_ads_create_customer_match_list`

Write write

Create a CRM-based user list for Customer Match.

Parameters: none

Generic CLI call

kosmo integrations:call google_ads.google_ads_create_customer_match_list '{}' --json

Provider shortcut

kosmo integrations:google_ads google_ads_create_customer_match_list '{}' --json

`google_ads.google_ads_run_customer_match_job`

Write write

Create, populate, and run an OfflineUserDataJob for audience uploads.

Parameters: none

Generic CLI call

kosmo integrations:call google_ads.google_ads_run_customer_match_job '{}' --json

Provider shortcut

kosmo integrations:google_ads google_ads_run_customer_match_job '{}' --json

`google_ads.google_ads_get_change_status`

Read read

List changed resources for sync workflows.

Parameters: none

Generic CLI call

kosmo integrations:call google_ads.google_ads_get_change_status '{}' --json

Provider shortcut

kosmo integrations:google_ads google_ads_get_change_status '{}' --json

`google_ads.google_ads_get_change_events`

Read read

List field-level recent account changes.

Parameters: none

Generic CLI call

kosmo integrations:call google_ads.google_ads_get_change_events '{}' --json

Provider shortcut

kosmo integrations:google_ads google_ads_get_change_events '{}' --json

`google_ads.google_ads_create_batch_job`

Write write

Create a batch job for large async operations.

Parameters: none

Generic CLI call

kosmo integrations:call google_ads.google_ads_create_batch_job '{}' --json

Provider shortcut

kosmo integrations:google_ads google_ads_create_batch_job '{}' --json

`google_ads.google_ads_mutate`

Write write

Governed resource-specific or mixed mutate escape hatch.

Parameters: none

Generic CLI call

kosmo integrations:call google_ads.google_ads_mutate '{}' --json

Provider shortcut

kosmo integrations:google_ads google_ads_mutate '{}' --json

`google_ads.google_ads_raw_request`

Write write

Low-level versioned Google Ads API request for advanced coverage.

Parameters: none

Generic CLI call

kosmo integrations:call google_ads.google_ads_raw_request '{}' --json

Provider shortcut

kosmo integrations:google_ads google_ads_raw_request '{}' --json

`google_ads.google_ads_list_billing_setups`

Read read

List billing setup resources.

Parameters: none

Generic CLI call

kosmo integrations:call google_ads.google_ads_list_billing_setups '{}' --json

Provider shortcut

kosmo integrations:google_ads google_ads_list_billing_setups '{}' --json

`google_ads.google_ads_account_budget_proposal`

Write write

Create account budget proposal operations for monthly invoicing accounts.

Parameters: none

Generic CLI call

kosmo integrations:call google_ads.google_ads_account_budget_proposal '{}' --json

Provider shortcut

kosmo integrations:google_ads google_ads_account_budget_proposal '{}' --json

`google_ads.google_ads_invite_user`

Write write

Invite a user to a Google Ads account.

Parameters: none

Generic CLI call

kosmo integrations:call google_ads.google_ads_invite_user '{}' --json

Provider shortcut

kosmo integrations:google_ads google_ads_invite_user '{}' --json

Function Schemas

Use these parameter tables when building CLI payloads without calling integrations:schema first.

`google_ads.google_ads_diagnostics`

Show safe configuration diagnostics.

Operation: Read read
Schema command: kosmo integrations:schema google_ads.google_ads_diagnostics --json

Parameter	Type	Required	Description
No parameters.

`google_ads.google_ads_list_accessible_customers`

List Google Ads customers directly accessible to the OAuth user.

Operation: Read read
Schema command: kosmo integrations:schema google_ads.google_ads_list_accessible_customers --json

Parameter	Type	Required	Description
No parameters.

`google_ads.google_ads_list_customer_clients`

List managed client accounts under a manager or customer.

Operation: Read read
Schema command: kosmo integrations:schema google_ads.google_ads_list_customer_clients --json

Parameter	Type	Required	Description
No parameters.

`google_ads.google_ads_search`

Run a paginated Google Ads Query Language search.

Operation: Read read
Schema command: kosmo integrations:schema google_ads.google_ads_search --json

Parameter	Type	Required	Description
No parameters.

`google_ads.google_ads_search_stream`

Run a streaming GAQL report for larger result sets.

Operation: Read read
Schema command: kosmo integrations:schema google_ads.google_ads_search_stream --json

Parameter	Type	Required	Description
No parameters.

`google_ads.google_ads_campaign_report`

Run a normalized campaign performance report.

Operation: Read read
Schema command: kosmo integrations:schema google_ads.google_ads_campaign_report --json

Parameter	Type	Required	Description
No parameters.

`google_ads.google_ads_ad_group_report`

Run a normalized ad group performance report.

Operation: Read read
Schema command: kosmo integrations:schema google_ads.google_ads_ad_group_report --json

Parameter	Type	Required	Description
No parameters.

`google_ads.google_ads_ad_report`

Run an ad and creative performance report.

Operation: Read read
Schema command: kosmo integrations:schema google_ads.google_ads_ad_report --json

Parameter	Type	Required	Description
No parameters.

`google_ads.google_ads_keyword_report`

Run a keyword performance report.

Operation: Read read
Schema command: kosmo integrations:schema google_ads.google_ads_keyword_report --json

Parameter	Type	Required	Description
No parameters.

`google_ads.google_ads_search_term_report`

Analyze search terms and query performance.

Operation: Read read
Schema command: kosmo integrations:schema google_ads.google_ads_search_term_report --json

Parameter	Type	Required	Description
No parameters.

`google_ads.google_ads_asset_report`

Report on assets and policy/performance labels.

Operation: Read read
Schema command: kosmo integrations:schema google_ads.google_ads_asset_report --json

Parameter	Type	Required	Description
No parameters.

`google_ads.google_ads_performance_max_report`

Report on Performance Max campaigns and asset groups.

Operation: Read read
Schema command: kosmo integrations:schema google_ads.google_ads_performance_max_report --json

Parameter	Type	Required	Description
No parameters.

`google_ads.google_ads_list_campaigns`

List campaigns with status, budget, channel, and optimization fields.

Operation: Read read
Schema command: kosmo integrations:schema google_ads.google_ads_list_campaigns --json

Parameter	Type	Required	Description
No parameters.

`google_ads.google_ads_create_campaign_budget`

Create a campaign budget with micros normalization.

Operation: Write write
Schema command: kosmo integrations:schema google_ads.google_ads_create_campaign_budget --json

Parameter	Type	Required	Description
No parameters.

`google_ads.google_ads_manage_campaign`

Create, update, pause, enable, or remove campaigns.

Operation: Write write
Schema command: kosmo integrations:schema google_ads.google_ads_manage_campaign --json

Parameter	Type	Required	Description
No parameters.

`google_ads.google_ads_manage_ad_group`

Create, update, pause, enable, or remove ad groups.

Operation: Write write
Schema command: kosmo integrations:schema google_ads.google_ads_manage_ad_group --json

Parameter	Type	Required	Description
No parameters.

`google_ads.google_ads_manage_keyword`

Add, update, or remove keyword criteria.

Operation: Write write
Schema command: kosmo integrations:schema google_ads.google_ads_manage_keyword --json

Parameter	Type	Required	Description
No parameters.

`google_ads.google_ads_manage_ad`

Create or manage responsive search ads and ad statuses.

Operation: Write write
Schema command: kosmo integrations:schema google_ads.google_ads_manage_ad --json

Parameter	Type	Required	Description
No parameters.

`google_ads.google_ads_manage_campaign_criteria`

Add or remove location, language, schedule, and negative criteria.

Operation: Write write
Schema command: kosmo integrations:schema google_ads.google_ads_manage_campaign_criteria --json

Parameter	Type	Required	Description
No parameters.

`google_ads.google_ads_upload_image_asset`

Create image assets from pre-encoded image metadata.

Operation: Write write
Schema command: kosmo integrations:schema google_ads.google_ads_upload_image_asset --json

Parameter	Type	Required	Description
No parameters.

`google_ads.google_ads_link_asset`

Link an asset to a customer, campaign, ad group, or asset group.

Operation: Write write
Schema command: kosmo integrations:schema google_ads.google_ads_link_asset --json

Parameter	Type	Required	Description
No parameters.

`google_ads.google_ads_create_search_campaign`

Create a complete paused Search campaign with budget, ad group, keywords, targets, and RSA.

Operation: Write write
Schema command: kosmo integrations:schema google_ads.google_ads_create_search_campaign --json

Parameter	Type	Required	Description
No parameters.

`google_ads.google_ads_create_performance_max_campaign`

Create a governed Performance Max campaign using mixed mutate operations.

Operation: Write write
Schema command: kosmo integrations:schema google_ads.google_ads_create_performance_max_campaign --json

Parameter	Type	Required	Description
No parameters.

`google_ads.google_ads_generate_keyword_ideas`

Generate keyword ideas and forecasts inputs.

Operation: Read read
Schema command: kosmo integrations:schema google_ads.google_ads_generate_keyword_ideas --json

Parameter	Type	Required	Description
No parameters.

`google_ads.google_ads_list_recommendations`

List optimization recommendations.

Operation: Read read
Schema command: kosmo integrations:schema google_ads.google_ads_list_recommendations --json

Parameter	Type	Required	Description
No parameters.

`google_ads.google_ads_apply_recommendations`

Apply selected recommendations with explicit confirmation.

Operation: Write write
Schema command: kosmo integrations:schema google_ads.google_ads_apply_recommendations --json

Parameter	Type	Required	Description
No parameters.

`google_ads.google_ads_upload_click_conversions`

Upload offline or enhanced lead click conversions.

Operation: Write write
Schema command: kosmo integrations:schema google_ads.google_ads_upload_click_conversions --json

Parameter	Type	Required	Description
No parameters.

`google_ads.google_ads_upload_call_conversions`

Upload offline call conversions.

Operation: Write write
Schema command: kosmo integrations:schema google_ads.google_ads_upload_call_conversions --json

Parameter	Type	Required	Description
No parameters.

`google_ads.google_ads_create_customer_match_list`

Create a CRM-based user list for Customer Match.

Operation: Write write
Schema command: kosmo integrations:schema google_ads.google_ads_create_customer_match_list --json

Parameter	Type	Required	Description
No parameters.

`google_ads.google_ads_run_customer_match_job`

Create, populate, and run an OfflineUserDataJob for audience uploads.

Operation: Write write
Schema command: kosmo integrations:schema google_ads.google_ads_run_customer_match_job --json

Parameter	Type	Required	Description
No parameters.

`google_ads.google_ads_get_change_status`

List changed resources for sync workflows.

Operation: Read read
Schema command: kosmo integrations:schema google_ads.google_ads_get_change_status --json

Parameter	Type	Required	Description
No parameters.

`google_ads.google_ads_get_change_events`

List field-level recent account changes.

Operation: Read read
Schema command: kosmo integrations:schema google_ads.google_ads_get_change_events --json

Parameter	Type	Required	Description
No parameters.

`google_ads.google_ads_create_batch_job`

Create a batch job for large async operations.

Operation: Write write
Schema command: kosmo integrations:schema google_ads.google_ads_create_batch_job --json

Parameter	Type	Required	Description
No parameters.

`google_ads.google_ads_mutate`

Governed resource-specific or mixed mutate escape hatch.

Operation: Write write
Schema command: kosmo integrations:schema google_ads.google_ads_mutate --json

Parameter	Type	Required	Description
No parameters.

`google_ads.google_ads_raw_request`

Low-level versioned Google Ads API request for advanced coverage.

Operation: Write write
Schema command: kosmo integrations:schema google_ads.google_ads_raw_request --json

Parameter	Type	Required	Description
No parameters.

`google_ads.google_ads_list_billing_setups`

List billing setup resources.

Operation: Read read
Schema command: kosmo integrations:schema google_ads.google_ads_list_billing_setups --json

Parameter	Type	Required	Description
No parameters.

`google_ads.google_ads_account_budget_proposal`

Create account budget proposal operations for monthly invoicing accounts.

Operation: Write write
Schema command: kosmo integrations:schema google_ads.google_ads_account_budget_proposal --json

Parameter	Type	Required	Description
No parameters.

`google_ads.google_ads_invite_user`

Invite a user to a Google Ads account.

Operation: Write write
Schema command: kosmo integrations:schema google_ads.google_ads_invite_user --json

Parameter	Type	Required	Description
No parameters.

Permissions

Headless calls still follow the integration read/write permission policy. Configure read/write defaults with integrations:configure. Add --force only for trusted automation that should bypass that policy.