Google Ads MCP Server
Provides tools for monitoring and managing Google Ads accounts, including performance reporting, arbitrary GAQL queries, budget updates, campaign/ad group/keyword management, negative keywords, geo targeting, ad schedules, and campaign/ad creation.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Google Ads MCP Server what's my campaign performance for last week?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Google Ads MCP Server (template)
A starting point you are meant to fork. Google's official googleads/google-ads-mcp is read-only and ships three tools. This template keeps that architecture and adds the write and reporting tools you need to actually manage an account, so you can clone it, point it at your own Google Cloud project, and cut it down to the tools your team should be allowed to call.
Start with the Complete Setup Guide, then delete what you do
not need from ads_mcp/tools/.
Set
GOOGLE_ADS_MCP_READ_ONLY=trueif you want the official server's read-only behaviour with this server's reporting tools.
A remote MCP server that lets Claude (and any other MCP-capable AI assistant) monitor and manage your Google Ads accounts: pull performance reports, run arbitrary GAQL queries, adjust budgets, pause/enable campaigns, add keywords and negative keywords, and create new campaigns and ads.
Built on the architecture of Google's official read-only googleads/google-ads-mcp server, extended with write/management tools and canned reports for routine (e.g. weekly) account reviews.
Tools
Monitoring (read-only)
Tool | What it does |
| Account IDs the authenticated user can access |
| Client accounts under a manager (MCC) account |
| Campaign metrics + status, budget, bidding strategy |
| Ad group metrics |
| Keyword metrics incl. quality score |
| Actual user queries — the input for negative keyword mining |
| Who/what changed in the account recently |
| Arbitrary GAQL query against any Google Ads resource |
| Field discovery for building |
| Audit what Smart Bidding optimizes toward |
| Audit a campaign's geo/schedule/device targeting |
| Resolve place names to geo target IDs |
All report tools accept predefined ranges (LAST_7_DAYS, LAST_30_DAYS, LAST_MONTH, …) or custom start_date/end_date.
Management (write)
Tool | What it does |
| Create or resize daily budgets |
| New Search/Display campaign — always created PAUSED |
| Pause / enable / remove a campaign |
| Create ad groups, change status or default CPC bid |
| New RSA — always created PAUSED |
| Pause / enable / remove an ad |
| Add or pause/enable/remove keywords |
| Campaign-level negative keywords |
| Promote/demote what bidding optimizes toward |
| Manage geo targeting |
| Restrict ads to staffed hours |
| Phone numbers on ads |
| Set target CPA on Maximize Conversions campaigns |
Safety rails:
Every write tool takes
validate_only=trueto preview a change without applying it.New campaigns and ads are always created paused so nothing spends money before you review it.
Set
GOOGLE_ADS_MCP_READ_ONLY=trueto hide all write tools entirely (monitoring-only deployments).
New user? Follow the step-by-step Complete Setup Guide — it covers the Google Ads manager account, developer token, the whole Google Cloud Console setup (project, billing, APIs, OAuth consent screen and client), Cloud Run deployment, connecting claude.ai, and a troubleshooting table of real-world errors.
Related MCP server: Google Ads MCP
Prerequisites
A Google Ads developer token — in a Google Ads manager account, go to Tools & Settings → Setup → API Center (direct link) and apply for a token. A "Basic" access token is enough for managing your own accounts. (docs)
Only have a regular (non-manager) account? The API Center is exclusive to manager accounts (MCC). Create a free one at ads.google.com/home/tools/manager-accounts — it's just an umbrella account with no ads or billing of its own — then link your existing account under it (Accounts → Sub-account settings → + → Link existing account) before applying, since Google's token review verifies the advertiser accounts beneath the manager. If the token is initially granted at "Test account" level, request Basic access from the same API Center page, and set
GOOGLE_ADS_LOGIN_CUSTOMER_IDto the manager account's ID when running this server.A Google Cloud project with an OAuth 2.0 client — in Google Cloud Console, create an OAuth client. Add your Google account as a test user on the consent screen (or publish the app) and include the scope
https://www.googleapis.com/auth/adwords. (docs)
Option 1 — Remote server for claude.ai (recommended)
This is the setup that lets claude.ai (web/mobile/desktop) connect as a custom connector, with each user signing in with their own Google account.
Deploy to Cloud Run
gcloud run deploy google-ads-mcp \
--source . \
--region us-central1 \
--allow-unauthenticated \
--set-env-vars "GOOGLE_ADS_DEVELOPER_TOKEN=YOUR_DEV_TOKEN" \
--set-env-vars "GOOGLE_ADS_MCP_OAUTH_CLIENT_ID=YOUR_CLIENT_ID" \
--set-env-vars "GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET=YOUR_CLIENT_SECRET" \
--set-env-vars "GOOGLE_ADS_MCP_BASE_URL=https://PLACEHOLDER"Then take the service URL Cloud Run prints (e.g. https://google-ads-mcp-xxxx-uc.a.run.app) and:
Re-deploy (or update the env var) with
GOOGLE_ADS_MCP_BASE_URLset to that URL.In Google Cloud Console, add
https://YOUR_SERVICE_URL/auth/callbackto the OAuth client's Authorized redirect URIs.
--allow-unauthenticatedis required so the MCP client can reach the endpoint; actual access is protected by the Google OAuth flow the server enforces. If you use a manager account, also setGOOGLE_ADS_LOGIN_CUSTOMER_ID.
Connect claude.ai
claude.ai → Settings → Connectors → Add custom connector.
URL:
https://YOUR_SERVICE_URL/mcp.Claude will walk you through the Google sign-in; grant the Google Ads scope.
Any other MCP client that supports streamable HTTP + OAuth (Claude Code, ChatGPT connectors, etc.) can connect the same way.
Option 2 — Local (stdio) for Claude Code / Claude Desktop
No deployment needed; credentials come from your environment.
pipx run --spec git+https://github.com/FlatbuzhZubumafu/google-ads-mcp-template.git google-ads-mcpClaude Code registration:
claude mcp add google-ads \
-e GOOGLE_ADS_DEVELOPER_TOKEN=YOUR_DEV_TOKEN \
-e GOOGLE_ADS_LOGIN_CUSTOMER_ID=YOUR_MCC_ID \
-- pipx run --spec git+https://github.com/FlatbuzhZubumafu/google-ads-mcp-template.git google-ads-mcpCredentials are resolved in this order:
OAuth token of the connected user (remote mode above).
Refresh token env vars:
GOOGLE_ADS_OAUTH_CLIENT_ID,GOOGLE_ADS_OAUTH_CLIENT_SECRET,GOOGLE_ADS_REFRESH_TOKEN.Application Default Credentials:
gcloud auth application-default login \ --scopes=https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform
See .env.example for every variable.
Running your ads on a weekly cadence
A workflow that works well once connected — save it as a project instruction or scheduled prompt for Claude:
get_campaign_performance(LAST_7_DAYSvs the previous week) — spot cost/conversion swings.get_search_terms_report— find wasted spend; propose negatives.get_keyword_performance— flag low quality scores and zero-conversion spenders.get_change_history— review everything that changed last week.Apply agreed changes (
add_negative_keywords,update_campaign_budget,set_campaign_status, …) — usingvalidate_only=truefirst, then for real after your confirmation.
Development
python -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/pytestRun locally over HTTP without OAuth (trusted networks only):
GOOGLE_ADS_MCP_TRANSPORT=http GOOGLE_ADS_DEVELOPER_TOKEN=... .venv/bin/google-ads-mcpDisclaimer
This server can spend and modify real money in your ad accounts. Review what your AI assistant proposes — especially budget changes and status changes — and prefer validate_only previews plus read-only mode wherever write access isn't needed. This is not an official Google product; portions are derived from googleads/google-ads-mcp (Apache 2.0).
Available Tools
31 toolsadd_keywordsAdd KeywordsC
Adds keywords to an ad group (ENABLED).
Inputs: keywords (required), ad_group_id (required), customer_id (required), cpc_bid, +2 more. Returns: object
add_location_targetingAdd Location TargetingA
Adds location targeting criteria to a campaign.
Resolve human-readable places to ids first with suggest_geo_targets.
Inputs: campaign_id (required), customer_id (required), geo_target_ids (required), negative, +1 more. Returns: object
add_negative_keywordsAdd Negative KeywordsA
Adds campaign-level negative keywords, preventing ads from showing
on those queries. The usual follow-up to reviewing
get_search_terms_report.
Inputs: keywords (required), campaign_id (required), customer_id (required), match_type, +1 more. Returns: object
create_ad_groupCreate Ad GroupB
Creates a standard search ad group (ENABLED) in a campaign.
Inputs: name (required), campaign_id (required), customer_id (required), cpc_bid, +1 more. Returns: object
create_call_assetCreate Call AssetA
Creates a call asset (clickable phone number shown with ads).
Returns its resource name; attach it to a campaign with
link_asset_to_campaign.
Inputs: customer_id (required), phone_number (required), country_code, validate_only, +1 more. Returns: object
create_campaignCreate CampaignA
Creates a new campaign in PAUSED state (so it never spends money
before a human reviews and enables it). Create a budget first with
create_campaign_budget.
Inputs: name (required), customer_id (required), budget_resource_name (required), end_date, +6 more. Returns: object
create_campaign_budgetCreate Campaign BudgetA
Creates a daily campaign budget. Returns its resource name, which is required when creating a campaign.
Inputs: name (required), customer_id (required), daily_amount (required), validate_only, +1 more. Returns: object
create_responsive_search_adCreate Responsive Search AdA
Creates a responsive search ad in PAUSED state (enable it with
set_ad_status after review).
Inputs: final_url (required), headlines (required), ad_group_id (required), customer_id (required), +4 more. Returns: object
get_account_hierarchyGet Account HierarchyARead-only
Lists all client accounts under a (manager) account, including the account itself.
Useful when the authenticated user works through an MCC/manager account: run this against the manager's customer ID to find the child account IDs to use with reporting and management tools.
Inputs: customer_id (required). Returns: result
get_ad_group_performanceGet Ad Group PerformanceBRead-only
Ad-group-level performance report with the core metrics (impressions, clicks, CTR, cost, conversions). Ordered by cost.
Inputs: customer_id (required), end_date, date_range, start_date, +1 more. Returns: result
get_campaign_performanceGet Campaign PerformanceARead-only
Campaign-level performance report: impressions, clicks, CTR, cost, conversions, conversion value, plus campaign status, bidding strategy and daily budget. Ordered by cost, highest first.
Cost and budget fields are in micros: divide by 1,000,000 for the account currency amount.
Inputs: customer_id (required), end_date, date_range, start_date, +1 more. Returns: result
get_change_historyGet Change HistoryARead-only
Recent changes made to the account (by users, tools, or this server): what changed, when, and by whom. Useful for a weekly review of account activity.
Inputs: customer_id (required), limit, days_back. Returns: result
get_keyword_performanceGet Keyword PerformanceARead-only
Keyword-level performance report: keyword text, match type, status, quality score, and the core metrics. Ordered by cost, highest first.
Inputs: customer_id (required), limit, end_date, date_range, +2 more. Returns: result
get_resource_metadataGet Resource MetadataARead-only
Retrieves the selectable, filterable, and sortable fields for a specific Google Ads resource, including compatible metrics and segments.
Use this tool to find out which fields you can select, filter by, or
sort by when querying a specific resource (e.g., 'campaign',
'ad_group') with the search tool. Metric and segment field names
start with 'metrics.' and 'segments.' respectively.
Do not guess fields — use this tool to discover them before constructing a query. Responses can be cached; they rarely change.
Inputs: resource_name (required). Returns: object
get_search_terms_reportGet Search Terms ReportARead-only
Search terms report: the actual user queries that triggered ads, with the core metrics. The main input for finding negative keyword candidates and new keyword opportunities. Ordered by cost.
Inputs: customer_id (required), limit, end_date, date_range, +2 more. Returns: result
link_asset_to_campaignLink Asset To CampaignB
Links an asset (e.g. a call asset) to a campaign so it serves with that campaign's ads.
Inputs: campaign_id (required), customer_id (required), asset_resource_name (required), field_type, +1 more. Returns: object
list_accessible_customersList Accessible CustomersARead-only
Returns the ids of Google Ads accounts directly accessible by the authenticated user.
Use this tool first to discover available customer IDs if the user hasn't provided one. Most other tools require a valid customer ID.
Returns: List[str]: A list of customer IDs (10-digit strings, no dashes).
Inputs: no named parameters. Returns: result
list_campaign_criteriaList Campaign CriteriaARead-only
Lists a campaign's targeting criteria: locations, proximity radii, ad schedules, devices, and negative criteria.
Inputs: campaign_id (required), customer_id (required). Returns: result
list_conversion_actionsList Conversion ActionsARead-only
Lists the account's conversion actions with category, type, status, and whether each is primary for optimization (primary_for_goal).
Use this to check what Smart Bidding is actually optimizing toward — e.g. whether phone calls are primary and page-view style actions are secondary.
Inputs: customer_id (required). Returns: result
remove_campaign_criterionRemove Campaign CriterionADestructive
Removes a single targeting criterion (e.g. a wrong location or an obsolete ad schedule) from a campaign.
Find criterion ids with list_campaign_criteria. Removing a criterion
only changes targeting; it does not touch ads, keywords, or budgets.
Inputs: campaign_id (required), customer_id (required), criterion_id (required), validate_only. Returns: object
searchSearchCRead-only
Fetches data from the Google Ads API using the search method.
Inputs: fields (required), resource (required), customer_id (required), limit, +2 more. Returns: result
set_ad_scheduleSet Ad ScheduleA
Adds ad schedule criteria to a campaign (which days/hours ads run).
A campaign with no ad schedule runs 24/7. Once any schedule entries exist, ads run ONLY during the scheduled windows — so include every window you want covered. Hours are in the account's time zone.
Inputs: schedule (required), campaign_id (required), customer_id (required), validate_only. Returns: object
set_ad_statusSet Ad StatusBDestructive
Pauses, enables, or removes an ad.
Inputs: ad_id (required), status (required), ad_group_id (required), customer_id (required), +1 more. Returns: object
set_campaign_conversion_goalsSet Campaign Conversion GoalsADestructive
Overrides, per campaign, which conversion goals Smart Bidding optimizes toward — regardless of the account-level primary/secondary settings.
Use this when account-level conversion actions can't be edited (e.g. system-generated "Local actions") but a campaign must optimize only to real outcomes such as phone calls. This switches the campaign to campaign-level goal configuration and sets each listed goal's biddable flag; include every category/origin combination that exists in the account, marking the ones to optimize toward biddable=true and the rest biddable=false.
Inputs: goals (required), campaign_id (required), customer_id (required), validate_only. Returns: object
set_campaign_statusSet Campaign StatusBDestructive
Pauses, enables, or removes a campaign.
Inputs: status (required), campaign_id (required), customer_id (required), validate_only. Returns: object
set_campaign_target_cpaSet Campaign Target CpaADestructive
Sets (or updates) the target CPA on a campaign that uses the Maximize Conversions bidding strategy.
Only do this once the campaign has ~30+ conversions of history; setting a tCPA too early or too low throttles delivery.
Inputs: target_cpa (required), campaign_id (required), customer_id (required), validate_only. Returns: object
set_conversion_action_primarySet Conversion Action PrimaryADestructive
Marks a conversion action as primary (optimized toward by Smart Bidding) or secondary (observed/reported only).
This is the main lever for making campaigns optimize toward real
outcomes (e.g. phone calls) instead of soft actions (page views,
direction clicks). Find ids with list_conversion_actions.
Note: some system-generated conversion actions cannot be edited via the API; the error will say so if this one can't.
Inputs: primary (required), customer_id (required), conversion_action_id (required), validate_only. Returns: object
set_keyword_statusSet Keyword StatusADestructive
Pauses, enables, or removes a keyword.
Find criterion ids with get_keyword_performance
(ad_group_criterion.criterion_id).
Inputs: status (required), ad_group_id (required), customer_id (required), criterion_id (required), +1 more. Returns: object
suggest_geo_targetsSuggest Geo TargetsARead-only
Resolves human-readable location names (e.g. 'Phoenix, Arizona', 'Gilbert, Arizona') to Google Ads geo target constant IDs, for use with add_location_targeting.
Inputs: location_names (required), country_code. Returns: result
update_ad_groupUpdate Ad GroupCDestructive
Updates an ad group's status and/or default max CPC bid.
Inputs: ad_group_id (required), customer_id (required), status, cpc_bid, +1 more. Returns: object
update_campaign_budgetUpdate Campaign BudgetADestructive
Changes the daily amount of an existing campaign budget.
Find the budget id via the search tool (campaign_budget.id) or from
a campaign's campaign.campaign_budget resource name.
Inputs: budget_id (required), customer_id (required), daily_amount (required), validate_only. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 31 tools
Most tools target a distinct resource and action, and the performance reports are clearly differentiated by level. However, the generic `search` tool overlaps conceptually with the prebuilt `get_*_performance` tools, and `list_accessible_customers` vs `get_account_hierarchy` could be confused for account discovery.
Nearly all tools follow a snake_case verb_noun pattern (e.g., create_campaign, set_ad_status, add_keywords). Minor deviations include the single-word `search` and mixed use of `list` vs `get` for retrieval operations.
At 31 tools, the set is well above the typical well-scoped range of 3–15. Several tools could be consolidated, such as the separate status setters (`set_ad_status`, `set_campaign_status`, `set_keyword_status`) and the budget create/update pair.
Core workflows for creating and pausing campaigns, ad groups, ads, and keywords are covered, along with reporting and conversion goal management. However, important update operations are missing, including changing campaign or ad group names, updating keyword bids, and editing ad copy beyond creation.
Maintenance
Related MCP Connectors
Manage Google Ads from ChatGPT, Claude or any MCP client. Sign in with OAuth or use an API key.
Hosted Google Ads MCP for Claude and ChatGPT. Preview every write. No developer token.
Google Ads MCP: reports, search terms, negatives, budgets, campaigns. Approval on every write.
Build, edit and sync Google, Microsoft, Reddit and Meta ad campaigns from your assistant.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables natural language access to Google Ads campaigns, accounts, and performance metrics via Claude, with tools for managing ad groups, keywords, budgets, and visualizing data.1-
- AlicenseNot gradedqualityCmaintenanceEnables natural-language analysis and management of Google Ads accounts, campaigns, keywords, budgets, and performance metrics through Claude.MIT
- AlicenseNot gradedqualityCmaintenanceEnables MCP clients such as Claude to manage Google Ads accounts through the Google Ads API, including performance reporting, keyword planning, search and P-MAX campaign creation, status changes, and budget updates.MIT
- AlicenseAqualityCmaintenanceEnables MCP clients such as Claude to read Google Ads performance reports, run keyword planner queries, and create or manage search and Performance Max campaigns, ad groups, keywords, ads, budgets, and delivery status. Write operations default to paused and can be disabled entirely for read-only analytics use.16MIT