Google Ads

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

التثبيت

أضف هذا إلى إعدادات MCP في عميلك (Claude Desktop: claude_desktop_config.json، وCursor: ‏.cursor/mcp.json، ويستخدم VS Code وغيره الصيغة نفسها «mcpServers»).

NPM package @zleventer/google-ads-mcp

Claude Code

claude mcp add google-ads -e 'GOOGLE_ADS_DEVELOPER_TOKEN=<your google_ads_developer_token>' -e 'GOOGLE_ADS_CLIENT_ID=<your google_ads_client_id>' -e 'GOOGLE_ADS_CLIENT_SECRET=<your google_ads_client_secret>' -e 'GOOGLE_ADS_REFRESH_TOKEN=<your google_ads_refresh_token>' -e 'GOOGLE_ADS_CUSTOMER_ID=<GOOGLE_ADS_CUSTOMER_ID>' -e 'GOOGLE_ADS_LOGIN_CUSTOMER_ID=<GOOGLE_ADS_LOGIN_CUSTOMER_ID>' -- npx -y @zleventer/google-ads-mcp@1.0.1

إعداد JSON (Claude Desktop وCursor وVS Code)

{
    "mcpServers": {
        "google-ads": {
            "command": "npx",
            "args": [
                "-y",
                "@zleventer/google-ads-mcp@1.0.1"
            ],
            "env": {
                "GOOGLE_ADS_DEVELOPER_TOKEN": "<your google_ads_developer_token>",
                "GOOGLE_ADS_CLIENT_ID": "<your google_ads_client_id>",
                "GOOGLE_ADS_CLIENT_SECRET": "<your google_ads_client_secret>",
                "GOOGLE_ADS_REFRESH_TOKEN": "<your google_ads_refresh_token>",
                "GOOGLE_ADS_CUSTOMER_ID": "<GOOGLE_ADS_CUSTOMER_ID>",
                "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "<GOOGLE_ADS_LOGIN_CUSTOMER_ID>"
            }
        }
    }
}

متغيرات البيئة

GOOGLE_ADS_DEVELOPER_TOKEN إلزامي سري Google Ads developer token (apply at https://developers.google.com/google-ads/api/docs/get-started/dev-token)
GOOGLE_ADS_CLIENT_ID إلزامي سري OAuth 2.0 client ID from Google Cloud Console
GOOGLE_ADS_CLIENT_SECRET إلزامي سري OAuth 2.0 client secret from Google Cloud Console
GOOGLE_ADS_REFRESH_TOKEN إلزامي سري OAuth 2.0 refresh token with https://www.googleapis.com/auth/adwords scope
GOOGLE_ADS_CUSTOMER_ID إلزامي Default Google Ads customer ID (numeric, no dashes). Can be overridden per tool call.
GOOGLE_ADS_LOGIN_CUSTOMER_ID Manager (MCC) account ID — required only if accessing accounts under an MCC

التوثيق

مأخوذ من ملف README للمشروع على GitHub ويُحدَّث أسبوعيًا. تفتح الروابط على GitHub.

المحتويات

google-ads-mcp
Why this exists
Example prompts
Demo
Features
Prerequisites
Environment variables
Usage
Tools reference
Build from source
License

google-ads-mcp

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

Category	Tools
Account	List accounts, account info
Campaigns	List campaigns, campaign performance, ad group performance
Keywords	Keyword performance, search terms report
Conversions	Conversions by campaign, list conversion actions
Ad Copy / RSAs	List RSAs with Ad Strength, RSA asset performance labels
Assets / Extensions	List account assets, campaign assets
Audiences	List user lists, campaign audience targeting
Performance	Geo performance, device performance, impression share, auction insights
Budget	List budgets, budget pacing
Escape hatch	Raw 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

Variable	Required	Description
`GOOGLE_ADS_DEVELOPER_TOKEN`	Yes	Your Google Ads developer token
`GOOGLE_ADS_CLIENT_ID`	Yes	OAuth 2.0 client ID
`GOOGLE_ADS_CLIENT_SECRET`	Yes	OAuth 2.0 client secret
`GOOGLE_ADS_REFRESH_TOKEN`	Yes	OAuth 2.0 refresh token
`GOOGLE_ADS_CUSTOMER_ID`	Yes*	Default customer ID (no dashes). Can be overridden per tool call.
`GOOGLE_ADS_LOGIN_CUSTOMER_ID`	No	Manager account ID for MCC access

Usage

Claude Desktop (`claude_desktop_config.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

{
  "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`)

{
  "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

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

Tool	Description
`gads_run_gaql`	Run any raw GAQL query — escape hatch for custom reports
`gads_list_accounts`	List all accessible Google Ads accounts
`gads_account_info`	Name, currency, timezone, manager flag, status
`gads_list_campaigns`	Campaigns with status, channel type, bidding strategy
`gads_campaign_performance`	Impressions, clicks, CTR, CPC, cost, conversions, CPA, ROAS
`gads_ad_group_performance`	Ad group metrics with campaign context
`gads_keyword_performance`	Keywords with match type, quality score, cost, conversions
`gads_search_terms_report`	Actual user queries that triggered ads — find negatives and opportunities
`gads_conversions_by_campaign`	Conversions × conversion action per campaign
`gads_list_conversion_actions`	All conversion actions with category, type, counting method
`gads_list_rsas`	RSAs with all headlines, descriptions, Ad Strength, approval status
`gads_rsa_asset_performance`	Per-asset performance labels: BEST / GOOD / LOW / PENDING / LEARNING
`gads_list_assets`	Account assets: sitelinks, callouts, structured snippets, images
`gads_campaign_assets`	Assets linked to campaigns with field type
`gads_list_audiences`	User lists (remarketing, customer match) with size and match rate
`gads_campaign_audience_targeting`	Audiences on campaigns with bid modifiers and inclusion/exclusion
`gads_geo_performance`	Performance by country, region, and city
`gads_device_performance`	Cost, conversions, CPA split by MOBILE / DESKTOP / TABLET
`gads_impression_share`	Search IS, Lost IS (Budget), Lost IS (Rank) per campaign
`gads_auction_insights`	Impression share, overlap rate, outranking share vs competitors
`gads_list_budgets`	All budgets: amount, delivery method, period, recommended budget
`gads_budget_pacing`	Cost vs budget per campaign with utilization %

Build from source

git clone https://github.com/ZLeventer/google-ads-mcp.git
cd google-ads-mcp
npm install
npm run build

License

الأسئلة الشائعة

ما هو Google Ads؟

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

كيف أثبّت Google Ads؟

يعمل على جهازك. في Claude Code: claude mcp add google-ads -e 'GOOGLE_ADS_DEVELOPER_TOKEN=<your google_ads_developer_token>' -e 'GOOGLE_ADS_CLIENT_ID=<your google_ads_client_id>' -e 'GOOGLE_ADS_CLIENT_SECRET=<your google_ads_client_secret>' -e 'GOOGLE_ADS_REFRESH_TOKEN=<your google_ads_refresh_token>' -e 'GOOGLE_ADS_CUSTOMER_ID=<GOOGLE_ADS_CUSTOMER_ID>' -e 'GOOGLE_ADS_LOGIN_CUSTOMER_ID=<GOOGLE_ADS_LOGIN_CUSTOMER_ID>' -- npx -y @zleventer/google-ads-mcp@1.0.1. وفي العملاء الآخرين، الصق إعداد JSON من هذه الصفحة في إعدادات MCP الخاصة بهم.

هل يحتاج Google Ads إلى مفتاح API؟

نعم. يتطلب GOOGLE_ADS_DEVELOPER_TOKEN, GOOGLE_ADS_CLIENT_ID, GOOGLE_ADS_CLIENT_SECRET, GOOGLE_ADS_REFRESH_TOKEN, GOOGLE_ADS_CUSTOMER_ID، وتضبطها في إعداداته.

هل Google Ads مفتوح المصدر؟

نعم. شيفرته متاحة على GitHub بترخيص MIT.

من يصون Google Ads؟

ينشره ZLeventer. يدرجه AI.tn لكنه لا يصونه ولا يوصي به.

من سجل MCP الرسمي. الإدراج ليس توصية: راجع شيفرة الخادم وصلاحياته قبل منحه الوصول إلى بياناتك.

تفاصيل الخادم

مُدرج في: سجل MCP الرسمي
الناشر: ZLeventer
الفئة: التسويق والمبيعات
طريقة التشغيل: محلي
نجوم GitHub: ★ 1
الترخيص: MIT
لغة البرمجة: TypeScript
آخر تحديث للشيفرة: ٢٩‏/٠٤‏/٢٠٢٦
المشكلات المفتوحة: 0
الإصدار: 1.0.1
نُشر في: ٢٦‏/٠٤‏/٢٠٢٦

io.github.ZLeventer/google-ads-mcp

خوادم مشابهة

Eclipse Aperture MCP The Instagram adapter, formalized: capability-declared, hash-bound native variants for ...
Eclipse Dispatch MCP Drafts once, syndicates drafts everywhere sanctioned, unifies the analytics. Never publ...
HeyLead — AI agent for LinkedIn outreach AI agent for LinkedIn outreach: finds the right people, writes in your voice, follows u...
Hermoso AI marketing agent and AI ad generator: 1037 tools, usable alone. No markup on models.
Rainbrand Rainbrand is the brand layer for agents.
GhostPaw Affinity Local relationship model and social CRM for contacts, relationships, evidence, and comm...
Web Validator by DigestSEO Audit public webpages and supplied markup for HTML, CSS, SEO, JSON-LD, and link issues.
Quattr AI Visibility MCP SEO MCP for Claude and ChatGPT: GSC, market share, AI citations, and CWV.

التسويق والمبيعات

Google Ads

التثبيت

التوثيق

google-ads-mcp

Why this exists

Example prompts

Demo

Features

Prerequisites

Environment variables

Usage

Claude Desktop (claude_desktop_config.json)

Claude Code

Cursor (~/.cursor/mcp.json)

Docker

Tools reference

Build from source

License

الأسئلة الشائعة

Claude Desktop (`claude_desktop_config.json`)

Cursor (`~/.cursor/mcp.json`)