Skip to main content
Glama
Google Ads MCP Server

Google Ads MCP Server

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=true if 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

list_accessible_customers

Account IDs the authenticated user can access

get_account_hierarchy

Client accounts under a manager (MCC) account

get_campaign_performance

Campaign metrics + status, budget, bidding strategy

get_ad_group_performance

Ad group metrics

get_keyword_performance

Keyword metrics incl. quality score

get_search_terms_report

Actual user queries — the input for negative keyword mining

get_change_history

Who/what changed in the account recently

search

Arbitrary GAQL query against any Google Ads resource

get_resource_metadata

Field discovery for building search queries

list_conversion_actions

Audit what Smart Bidding optimizes toward

list_campaign_criteria

Audit a campaign's geo/schedule/device targeting

suggest_geo_targets

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_campaign_budget / update_campaign_budget

Create or resize daily budgets

create_campaign

New Search/Display campaign — always created PAUSED

set_campaign_status

Pause / enable / remove a campaign

create_ad_group / update_ad_group

Create ad groups, change status or default CPC bid

create_responsive_search_ad

New RSA — always created PAUSED

set_ad_status

Pause / enable / remove an ad

add_keywords / set_keyword_status

Add or pause/enable/remove keywords

add_negative_keywords

Campaign-level negative keywords

set_conversion_action_primary

Promote/demote what bidding optimizes toward

add_location_targeting / remove_campaign_criterion

Manage geo targeting

set_ad_schedule

Restrict ads to staffed hours

create_call_asset / link_asset_to_campaign

Phone numbers on ads

set_campaign_target_cpa

Set target CPA on Maximize Conversions campaigns

Safety rails:

  • Every write tool takes validate_only=true to 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=true to 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

  1. 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_ID to the manager account's ID when running this server.

  2. 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)

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:

  1. Re-deploy (or update the env var) with GOOGLE_ADS_MCP_BASE_URL set to that URL.

  2. In Google Cloud Console, add https://YOUR_SERVICE_URL/auth/callback to the OAuth client's Authorized redirect URIs.

--allow-unauthenticated is 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 set GOOGLE_ADS_LOGIN_CUSTOMER_ID.

Connect claude.ai

  1. claude.ai → Settings → Connectors → Add custom connector.

  2. URL: https://YOUR_SERVICE_URL/mcp.

  3. 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-mcp

Claude 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-mcp

Credentials are resolved in this order:

  1. OAuth token of the connected user (remote mode above).

  2. Refresh token env vars: GOOGLE_ADS_OAUTH_CLIENT_ID, GOOGLE_ADS_OAUTH_CLIENT_SECRET, GOOGLE_ADS_REFRESH_TOKEN.

  3. 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:

  1. get_campaign_performance (LAST_7_DAYS vs the previous week) — spot cost/conversion swings.

  2. get_search_terms_report — find wasted spend; propose negatives.

  3. get_keyword_performance — flag low quality scores and zero-conversion spenders.

  4. get_change_history — review everything that changed last week.

  5. Apply agreed changes (add_negative_keywords, update_campaign_budget, set_campaign_status, …) — using validate_only=true first, then for real after your confirmation.

Development

python -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/pytest

Run locally over HTTP without OAuth (trusted networks only):

GOOGLE_ADS_MCP_TRANSPORT=http GOOGLE_ADS_DEVELOPER_TOKEN=... .venv/bin/google-ads-mcp

Disclaimer

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 tools
add_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 HierarchyA
Read-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 PerformanceB
Read-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 PerformanceA
Read-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 HistoryA
Read-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 PerformanceA
Read-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 MetadataA
Read-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 ReportA
Read-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

list_accessible_customersList Accessible CustomersA
Read-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 CriteriaA
Read-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 ActionsA
Read-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 CriterionA
Destructive

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

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 StatusB
Destructive

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 GoalsA
Destructive

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 StatusB
Destructive

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 CpaA
Destructive

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 PrimaryA
Destructive

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 StatusA
Destructive

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 TargetsA
Read-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 GroupC
Destructive

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 BudgetA
Destructive

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

    B3.2/5.0

    Scored across 31 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count2/5

    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.

    Completeness3/5

    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

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables 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
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables natural-language analysis and management of Google Ads accounts, campaigns, keywords, budgets, and performance metrics through Claude.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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
    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      16
      MIT