VX Agents

OpenAPI Marketplace

google-ads

v1.0.2 · 8 endpoints · 4 connections · shared by linh

Read and manage a Google Ads account: performance reporting through the Google Ads Query Language (GAQL), and create/update/remove operations for campaign budgets, campaigns, ad groups, responsive search ads, keywords and campaign-level targeting.

Connect this API to an AI agent Browse all specs

What you can do with google-ads via MCP

Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.

MethodPathOperationDescription
GET /customers:listAccessibleCustomers listAccessibleGoogleAdsCustomers List the Google Ads accounts the connected user can access Method: GET Path: /customers:listAccessibleCustomers
POST /customers/{customerId}/googleAds:search searchGoogleAds Read Google Ads data with a GAQL query Method: POST Path: /customers/{customerId}/googleAds:search IMPORTANT: This function has 2 REQUIRED parameter(s) and 1 OPTIONAL parameter(s) REQUIRED parameters MUST be provided OPTIONAL parameters can be omitted if not needed Parameters: Path Parameters: REQUIRED: - customerId: The 10-digit Google Ads account ID the operation acts on, with no hyphens ("123-456-7890" is passed as "1234567890"). This is the account being read or changed, not the manager account. Get it from listAccessibleGoogleAdsCustomers or ask the user. Request Body: REQUIRED: - query: The GAQL query. Field names are snake_case, exactly one resource in FROM, and any query selecting metrics needs a segments.date filter. OPTIONAL: - pageToken: nextPageToken from a previous response, to fetch the next page.
POST /customers/{customerId}/campaignBudgets:mutate mutateGoogleAdsCampaignBudgets Create, update or remove campaign budgets Method: POST Path: /customers/{customerId}/campaignBudgets:mutate IMPORTANT: This function has 2 REQUIRED parameter(s) and 2 OPTIONAL parameter(s) REQUIRED parameters MUST be provided OPTIONAL parameters can be omitted if not needed Parameters: Path Parameters: REQUIRED: - customerId: The 10-digit Google Ads account ID the operation acts on, with no hyphens ("123-456-7890" is passed as "1234567890"). This is the account being read or changed, not the manager account. Get it from listAccessibleGoogleAdsCustomers or ask the user. Request Body: REQUIRED: - operations: operations array OPTIONAL: - partialFailure: When true, valid operations are carried out and failed ones are reported in partialFailureError — the response is still HTTP 200, so a 200 does not by itself mean every operation succeeded. Always read partialFailureError before reporting success. When false (the default) any single error rolls back the whole request. - validateOnly: When true the request is validated and nothing is changed. Use it to dry-run a mutation before asking the user to confirm.
POST /customers/{customerId}/campaigns:mutate mutateGoogleAdsCampaigns Create, update, pause or remove campaigns Method: POST Path: /customers/{customerId}/campaigns:mutate IMPORTANT: This function has 2 REQUIRED parameter(s) and 2 OPTIONAL parameter(s) REQUIRED parameters MUST be provided OPTIONAL parameters can be omitted if not needed Parameters: Path Parameters: REQUIRED: - customerId: The 10-digit Google Ads account ID the operation acts on, with no hyphens ("123-456-7890" is passed as "1234567890"). This is the account being read or changed, not the manager account. Get it from listAccessibleGoogleAdsCustomers or ask the user. Request Body: REQUIRED: - operations: operations array OPTIONAL: - partialFailure: When true, valid operations are carried out and failed ones are reported in partialFailureError — the response is still HTTP 200, so a 200 does not by itself mean every operation succeeded. Always read partialFailureError before reporting success. When false (the default) any single error rolls back the whole request. - validateOnly: When true the request is validated and nothing is changed. Use it to dry-run a mutation before asking the user to confirm.
POST /customers/{customerId}/adGroups:mutate mutateGoogleAdsAdGroups Create, update, pause or remove ad groups Method: POST Path: /customers/{customerId}/adGroups:mutate IMPORTANT: This function has 2 REQUIRED parameter(s) and 2 OPTIONAL parameter(s) REQUIRED parameters MUST be provided OPTIONAL parameters can be omitted if not needed Parameters: Path Parameters: REQUIRED: - customerId: The 10-digit Google Ads account ID the operation acts on, with no hyphens ("123-456-7890" is passed as "1234567890"). This is the account being read or changed, not the manager account. Get it from listAccessibleGoogleAdsCustomers or ask the user. Request Body: REQUIRED: - operations: operations array OPTIONAL: - partialFailure: When true, valid operations are carried out and failed ones are reported in partialFailureError — the response is still HTTP 200, so a 200 does not by itself mean every operation succeeded. Always read partialFailureError before reporting success. When false (the default) any single error rolls back the whole request. - validateOnly: When true the request is validated and nothing is changed. Use it to dry-run a mutation before asking the user to confirm.
POST /customers/{customerId}/adGroupAds:mutate mutateGoogleAdsAdGroupAds Create, pause or remove ads inside an ad group Method: POST Path: /customers/{customerId}/adGroupAds:mutate IMPORTANT: This function has 2 REQUIRED parameter(s) and 2 OPTIONAL parameter(s) REQUIRED parameters MUST be provided OPTIONAL parameters can be omitted if not needed Parameters: Path Parameters: REQUIRED: - customerId: The 10-digit Google Ads account ID the operation acts on, with no hyphens ("123-456-7890" is passed as "1234567890"). This is the account being read or changed, not the manager account. Get it from listAccessibleGoogleAdsCustomers or ask the user. Request Body: REQUIRED: - operations: operations array OPTIONAL: - partialFailure: When true, valid operations are carried out and failed ones are reported in partialFailureError — the response is still HTTP 200, so a 200 does not by itself mean every operation succeeded. Always read partialFailureError before reporting success. When false (the default) any single error rolls back the whole request. - validateOnly: When true the request is validated and nothing is changed. Use it to dry-run a mutation before asking the user to confirm.
POST /customers/{customerId}/adGroupCriteria:mutate mutateGoogleAdsAdGroupCriteria Add, re-bid, pause or remove keywords in an ad group Method: POST Path: /customers/{customerId}/adGroupCriteria:mutate IMPORTANT: This function has 2 REQUIRED parameter(s) and 2 OPTIONAL parameter(s) REQUIRED parameters MUST be provided OPTIONAL parameters can be omitted if not needed Parameters: Path Parameters: REQUIRED: - customerId: The 10-digit Google Ads account ID the operation acts on, with no hyphens ("123-456-7890" is passed as "1234567890"). This is the account being read or changed, not the manager account. Get it from listAccessibleGoogleAdsCustomers or ask the user. Request Body: REQUIRED: - operations: operations array OPTIONAL: - partialFailure: When true, valid operations are carried out and failed ones are reported in partialFailureError — the response is still HTTP 200, so a 200 does not by itself mean every operation succeeded. Always read partialFailureError before reporting success. When false (the default) any single error rolls back the whole request. - validateOnly: When true the request is validated and nothing is changed. Use it to dry-run a mutation before asking the user to confirm.
POST /customers/{customerId}/campaignCriteria:mutate mutateGoogleAdsCampaignCriteria Manage campaign-level targeting and negative keywords Method: POST Path: /customers/{customerId}/campaignCriteria:mutate IMPORTANT: This function has 2 REQUIRED parameter(s) and 2 OPTIONAL parameter(s) REQUIRED parameters MUST be provided OPTIONAL parameters can be omitted if not needed Parameters: Path Parameters: REQUIRED: - customerId: The 10-digit Google Ads account ID the operation acts on, with no hyphens ("123-456-7890" is passed as "1234567890"). This is the account being read or changed, not the manager account. Get it from listAccessibleGoogleAdsCustomers or ask the user. Request Body: REQUIRED: - operations: operations array OPTIONAL: - partialFailure: When true, valid operations are carried out and failed ones are reported in partialFailureError — the response is still HTTP 200, so a 200 does not by itself mean every operation succeeded. Always read partialFailureError before reporting success. When false (the default) any single error rolls back the whole request. - validateOnly: When true the request is validated and nothing is changed. Use it to dry-run a mutation before asking the user to confirm.

Usage guide

## Step 1: Get a Developer Token 1. Sign in to your **Google Ads Manager Account (MCC)**. *(If you don't have one, create a Manager Account at [ads.google.com](https://ads.google.com)).* 2. Click **Tools & Settings** (wrench icon) > **Setup** > **API Center**. 3. Fill in the required application info to generate a **Developer Token**. 4. Save your `Developer Token` (it starts as Test Access / Basic Access, which works for API testing). --- ## Step 2: Create OAuth 2.0 Credentials in Google Cloud 1. Go to the [Google Cloud Console](https://console.cloud.google.com/). 2. Create a new project or select an existing project. 3. In the left menu, go to **APIs & Services** > **Library**. 4. Search for **Google Ads API** and click **Enable**. 5. Go to **APIs & Services** > **OAuth consent screen**: - Choose **External** (or Internal for Workspace). - Add your email and app details. - Under **Scopes**, add `https://www.googleapis.com/auth/adwords`. - Add your email to **Test users** if your app status is "Testing". 6. Go to **APIs & Services** > **Credentials**: - Click **Create Credentials** > **OAuth client ID**. - Application type: Select **Web application** or **Desktop app**. - If Web app, set **Authorized redirect URIs** to `https://developers.google.com/oauthplayground` (useful for getting tokens easily). - Click **Create** and copy your **Client ID** and **Client Secret**. ---

How to use this spec

  1. Create a free VX Agents account (sandbox tools included).
  2. Open the marketplace and connect “google-ads” to an agent.
  3. Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.