google-ads
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.
| Method | Path | Operation | Description |
|---|---|---|---|
| GET | /customers:listAccessibleCustomers |
listAccessibleGoogleAdsCustomers | List the Google Ads accounts the connected user can access |
| POST | /customers/{customerId}/googleAds:search |
searchGoogleAds | Read Google Ads data with a GAQL query |
| POST | /customers/{customerId}/campaignBudgets:mutate |
mutateGoogleAdsCampaignBudgets | Create, update or remove campaign budgets |
| POST | /customers/{customerId}/campaigns:mutate |
mutateGoogleAdsCampaigns | Create, update, pause or remove campaigns |
| POST | /customers/{customerId}/adGroups:mutate |
mutateGoogleAdsAdGroups | Create, update, pause or remove ad groups |
| POST | /customers/{customerId}/adGroupAds:mutate |
mutateGoogleAdsAdGroupAds | Create, pause or remove ads inside an ad group |
| POST | /customers/{customerId}/adGroupCriteria:mutate |
mutateGoogleAdsAdGroupCriteria | Add, re-bid, pause or remove keywords in an ad group |
| POST | /customers/{customerId}/campaignCriteria:mutate |
mutateGoogleAdsCampaignCriteria | Manage campaign-level targeting and negative keywords |
| POST | /customers/{customerId}/assets:mutate |
mutateGoogleAdsAssets | Create the assets ads are built from |
| POST | /customers/{customerId}/userLists:mutate |
mutateGoogleAdsUserLists | Create and update audience lists |
| POST | /googleAdsFields:search |
searchGoogleAdsFields | Look up which fields exist, and how they can be used |
| POST | /customers/{customerId}/recommendations:apply |
applyGoogleAdsRecommendations | Apply a recommendation Google has made |
| POST | /customers/{customerId}/recommendations:dismiss |
dismissGoogleAdsRecommendations | Dismiss a recommendation so Google stops suggesting it |
| POST | /customers/{customerId}/conversionActions:mutate |
mutateGoogleAdsConversionActions | Create and update conversion actions |
| POST | /customers/{customerId}/audiences:mutate |
mutateGoogleAdsAudiences | Build an audience out of segments |
Authentication
GoogleAdsOAuth2
OAuth 2.0
Scopes: https://www.googleapis.com/auth/adwords
Google OAuth2 Authorization Code flow with PKCE. The authorization URL requests offline access and explicit consent so Google returns a refresh token and the connection keeps working past the first hour. The connected Google user must have access to the Google Ads account.
GoogleAdsDeveloperToken
API key — sent as the developer-token header
The developer token from the Google Ads manager account's API Center. Required on every call, alongside the OAuth2 token. Set it once as a static header on the spec; it is a credential and never a parameter the model supplies.
Accounts accessed through a manager account also need a static
login-customer-id header holding the manager's 10-digit ID.
Usage guide
Step 1: Get a Developer Token
- Sign in to your Google Ads Manager Account (MCC). (If you don't have one, create a Manager Account at ads.google.com).
- Click Tools & Settings (wrench icon) > Setup > API Center.
- Fill in the required application info to generate a Developer Token.
- 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
- Go to the Google Cloud Console.
- Create a new project or select an existing project.
- In the left menu, go to APIs & Services > Library.
- Search for Google Ads API and click Enable.
- 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".
- 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
- Create a free VX Agents account (sandbox tools included).
- Open the marketplace and connect “google-ads” to an agent.
- Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.