Google Ads

io.github.ZLeventerPublished by GitHub account ZLeventerv1.0.1Updated Oct 24, 2026

MCP server for Google Ads — 22 tools for spend diagnosis, impression share, and asset performance.

VerifiedSTDIODesktop onlyData & AnalyticsBusiness & Commerce

Overview

AI-generated overview

A local MCP server that gives an assistant read access to Google Ads data for spend diagnosis, impression share, auction insights and asset performance.

What you can do
List accessible accounts and account details, campaigns, ad groups and budgets with pacing and utilization figures. Review keyword performance, search terms and conversions by campaign or conversion action. Inspect responsive search ads, ad strength and per-asset performance labels, plus account and campaign assets. Examine audiences and campaign audience targeting, geo and device splits, impression share and auction insights against competitors. Run arbitrary GAQL queries as an escape hatch for custom reports.
When to use it
Useful for paid search teams and agencies that want to diagnose wasted spend, budget limits, weak ad assets or lost impression share conversationally instead of building dashboards. Best when the assistant needs to answer specific performance questions about a Google Ads account.
Requirements
Runs locally via npx or Node.js 20 or later, or as a Docker container. Needs a Google Ads developer token, OAuth 2.0 client ID and client secret from Google Cloud Console, and a refresh token with the adwords scope, supplied as environment variables. A default customer ID is required and can be overridden per call; a manager account ID is needed only for MCC access. Network access to Google Ads is required.
Before you install
Requires long-lived Google Ads credentials, including a refresh token and developer token, stored in the local configuration; anyone with access to that configuration can query the ad account. The raw GAQL tool can run any query the credentials permit, so scope the account and review what the assistant sends. Data from the ad account is sent to the model provider as part of the conversation.

Installation

In SourceWeft

  1. Open Google Ads in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

google-ads-mcp

[npm version] [npm downloads] [glama score] [Node.js] [MCP] [License: MIT]

MCP server for Google Ads — diagnose spend efficiency, impression share, and asset performance from Claude.

22 tools across campaigns, keywords, RSAs, assets, audiences, geo/device splits, impression share, auction insights, and budget pacing — plus a raw GAQL escape hatch. Built for B2B paid search teams and agencies running real diagnosis, not just dashboard-style "list my campaigns" queries.

Why this exists

Most Google Ads MCP servers stop at "list campaigns + basic metrics." This one goes after the questions paid search teams actually ask: which RSA assets are labeled LOW so I can replace them, which keywords burn budget with zero conversions, who am I losing impression share to in auction insights, what's my mobile vs. desktop CPA gap, which campaigns are budget-limited right now. Those are the levers you pull to fix performance — and they're all first-class tools here.

Differentiated from the official googleads/google-ads-mcp: ships RSA asset performance labels, auction insights, impression share analysis, geo/device splits, audience targeting inspection, and budget pacing.

Example prompts

Once installed, ask Claude things like:

  • "What's my impression share vs competitors this month? Who am I most often losing to?"
  • "Show all RSA assets with LOW performance labels so I can replace them."
  • "Which keywords are spending the most with zero conversions in the last 30 days?"
  • "What's my mobile vs. desktop CPA difference across all campaigns?"
  • "Are any campaigns budget-limited right now? Show Lost IS (Budget)."
  • "List my remarketing audiences and tell me which ones are large enough to target in Search."

Demo

🎥 Walkthrough video coming soon — diagnosing wasted spend from Claude in under 60 seconds.

Features

CategoryTools
AccountList accounts, account info
CampaignsList campaigns, campaign performance, ad group performance
KeywordsKeyword performance, search terms report
ConversionsConversions by campaign, list conversion actions
Ad Copy / RSAsList RSAs with Ad Strength, RSA asset performance labels
Assets / ExtensionsList account assets, campaign assets
AudiencesList user lists, campaign audience targeting
PerformanceGeo performance, device performance, impression share, auction insights
BudgetList budgets, budget pacing
Escape hatchRaw GAQL query

Prerequisites

  • Node.js 20+
  • A Google Ads Developer Token (apply here)
  • OAuth 2.0 credentials (Client ID + Secret) from Google Cloud Console
  • A refresh token with https://www.googleapis.com/auth/adwords scope

Environment variables

VariableRequiredDescription
GOOGLE_ADS_DEVELOPER_TOKENYesYour Google Ads developer token
GOOGLE_ADS_CLIENT_IDYesOAuth 2.0 client ID
GOOGLE_ADS_CLIENT_SECRETYesOAuth 2.0 client secret
GOOGLE_ADS_REFRESH_TOKENYesOAuth 2.0 refresh token
GOOGLE_ADS_CUSTOMER_IDYes*Default customer ID (no dashes). Can be overridden per tool call.
GOOGLE_ADS_LOGIN_CUSTOMER_IDNoManager account ID for MCC access

Usage

Claude Desktop (claude_desktop_config.json)

json
{  "mcpServers": {    "google-ads": {      "command": "npx",      "args": ["-y", "google-ads-mcp"],      "env": {        "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_TOKEN",        "GOOGLE_ADS_CLIENT_ID": "YOUR_CLIENT_ID",        "GOOGLE_ADS_CLIENT_SECRET": "YOUR_CLIENT_SECRET",        "GOOGLE_ADS_REFRESH_TOKEN": "YOUR_REFRESH_TOKEN",        "GOOGLE_ADS_CUSTOMER_ID": "1234567890"      }    }  }}

Claude Code

json
{  "mcpServers": {    "google-ads": {      "command": "node",      "args": ["/path/to/google-ads-mcp/dist/index.js"],      "env": {        "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_TOKEN",        "GOOGLE_ADS_CLIENT_ID": "YOUR_CLIENT_ID",        "GOOGLE_ADS_CLIENT_SECRET": "YOUR_CLIENT_SECRET",        "GOOGLE_ADS_REFRESH_TOKEN": "YOUR_REFRESH_TOKEN",        "GOOGLE_ADS_CUSTOMER_ID": "1234567890"      }    }  }}

Cursor (~/.cursor/mcp.json)

json
{  "mcpServers": {    "google-ads": {      "command": "npx",      "args": ["-y", "google-ads-mcp"],      "env": {        "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_TOKEN",        "GOOGLE_ADS_CLIENT_ID": "YOUR_CLIENT_ID",        "GOOGLE_ADS_CLIENT_SECRET": "YOUR_CLIENT_SECRET",        "GOOGLE_ADS_REFRESH_TOKEN": "YOUR_REFRESH_TOKEN",        "GOOGLE_ADS_CUSTOMER_ID": "1234567890"      }    }  }}

Docker

bash
docker build -t google-ads-mcp .docker run --rm \  -e GOOGLE_ADS_DEVELOPER_TOKEN=YOUR_TOKEN \  -e GOOGLE_ADS_CLIENT_ID=YOUR_CLIENT_ID \  -e GOOGLE_ADS_CLIENT_SECRET=YOUR_CLIENT_SECRET \  -e GOOGLE_ADS_REFRESH_TOKEN=YOUR_REFRESH_TOKEN \  -e GOOGLE_ADS_CUSTOMER_ID=1234567890 \  google-ads-mcp

Tools reference

ToolDescription
gads_run_gaqlRun any raw GAQL query — escape hatch for custom reports
gads_list_accountsList all accessible Google Ads accounts
gads_account_infoName, currency, timezone, manager flag, status
gads_list_campaignsCampaigns with status, channel type, bidding strategy
gads_campaign_performanceImpressions, clicks, CTR, CPC, cost, conversions, CPA, ROAS
gads_ad_group_performanceAd group metrics with campaign context
gads_keyword_performanceKeywords with match type, quality score, cost, conversions
gads_search_terms_reportActual user queries that triggered ads — find negatives and opportunities
gads_conversions_by_campaignConversions × conversion action per campaign
gads_list_conversion_actionsAll conversion actions with category, type, counting method
gads_list_rsasRSAs with all headlines, descriptions, Ad Strength, approval status
gads_rsa_asset_performancePer-asset performance labels: BEST / GOOD / LOW / PENDING / LEARNING
gads_list_assetsAccount assets: sitelinks, callouts, structured snippets, images
gads_campaign_assetsAssets linked to campaigns with field type
gads_list_audiencesUser lists (remarketing, customer match) with size and match rate
gads_campaign_audience_targetingAudiences on campaigns with bid modifiers and inclusion/exclusion
gads_geo_performancePerformance by country, region, and city
gads_device_performanceCost, conversions, CPA split by MOBILE / DESKTOP / TABLET
gads_impression_shareSearch IS, Lost IS (Budget), Lost IS (Rank) per campaign
gads_auction_insightsImpression share, overlap rate, outranking share vs competitors
gads_list_budgetsAll budgets: amount, delivery method, period, recommended budget
gads_budget_pacingCost vs budget per campaign with utilization %

Build from source

bash
git clone https://github.com/ZLeventer/google-ads-mcp.gitcd google-ads-mcpnpm installnpm run build

License

MIT — Copyright (c) 2026 Zach Leventer

Source: README.md at commit ceaa0dc

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v1.0.1LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts