de en es ja ko ru zh

google-ads-mcp

Name: google-ads-mcp
Author: ZLeventer

by ZLeventer

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

google-ads-mcp

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

Claude에서 지출 효율성, 노출 점유율, 에셋 성과를 진단하기 위한 Google Ads용 MCP 서버입니다.

캠페인, 키워드, RSA, 에셋, 잠재고객, 지역/기기 구분, 노출 점유율, 경매 통찰력, 예산 페이싱을 아우르는 22가지 도구와 원시 GAQL 탈출구를 제공합니다. 단순히 "내 캠페인 나열"과 같은 대시보드 스타일의 쿼리가 아닌, 실제 진단을 수행하는 B2B 검색 광고 팀과 대행사를 위해 구축되었습니다.

이 프로젝트의 존재 이유

대부분의 Google Ads MCP 서버는 "캠페인 나열 + 기본 지표" 수준에서 멈춥니다. 이 서버는 검색 광고 팀이 실제로 묻는 질문들을 해결합니다: 교체할 수 있도록 LOW로 표시된 RSA 에셋은 무엇인가, 전환 없이 예산만 소진하는 키워드는 무엇인가, 경매 통찰력에서 노출 점유율을 잃고 있는 대상은 누구인가, 모바일 대 데스크톱 CPA 격차는 얼마인가, 현재 예산 제한이 걸린 캠페인은 무엇인가. 이러한 질문들은 성과를 개선하기 위해 필요한 핵심 요소이며, 여기서는 모두 일급 도구로 제공됩니다.

공식 googleads/google-ads-mcp와 차별화되는 점: RSA 에셋 성과 라벨, 경매 통찰력, 노출 점유율 분석, 지역/기기 구분, 잠재고객 타겟팅 검사, 예산 페이싱 기능을 제공합니다.

Related MCP server: adops-mcp

예시 프롬프트

설치 후 Claude에게 다음과 같이 질문해 보세요:

"이번 달 경쟁사 대비 내 노출 점유율은 어떤가요? 가장 자주 밀리는 상대는 누구인가요?"
"교체할 수 있도록 성과 라벨이 LOW인 모든 RSA 에셋을 보여주세요."
"지난 30일 동안 전환 없이 가장 많은 비용을 지출한 키워드는 무엇인가요?"
"모든 캠페인에 걸쳐 모바일과 데스크톱의 CPA 차이는 어떻게 되나요?"
"현재 예산 제한이 걸린 캠페인이 있나요? 노출 점유율 손실(예산)을 보여주세요."
"내 리마케팅 잠재고객 목록을 나열하고 검색 광고에서 타겟팅할 만큼 규모가 큰 목록이 무엇인지 알려주세요."

데모

🎥 워크스루 영상 곧 공개 예정 — Claude에서 60초 이내에 낭비되는 지출을 진단하는 방법.

기능

카테고리	도구
계정	계정 나열, 계정 정보
캠페인	캠페인 나열, 캠페인 성과, 광고 그룹 성과
키워드	키워드 성과, 검색어 보고서
전환	캠페인별 전환, 전환 액션 나열
광고 문구 / RSA	광고 강도가 포함된 RSA 나열, RSA 에셋 성과 라벨
에셋 / 확장	계정 에셋 나열, 캠페인 에셋
잠재고객	사용자 목록 나열, 캠페인 잠재고객 타겟팅
성과	지역 성과, 기기 성과, 노출 점유율, 경매 통찰력
예산	예산 나열, 예산 페이싱
탈출구	원시 GAQL 쿼리

사전 요구 사항

Node.js 20+
Google Ads 개발자 토큰 (여기서 신청)
Google Cloud Console에서 발급받은 OAuth 2.0 자격 증명 (클라이언트 ID + 비밀번호)
https://www.googleapis.com/auth/adwords 범위가 포함된 새로 고침 토큰

환경 변수

변수	필수	설명
`GOOGLE_ADS_DEVELOPER_TOKEN`	예	Google Ads 개발자 토큰
`GOOGLE_ADS_CLIENT_ID`	예	OAuth 2.0 클라이언트 ID
`GOOGLE_ADS_CLIENT_SECRET`	예	OAuth 2.0 클라이언트 비밀번호
`GOOGLE_ADS_REFRESH_TOKEN`	예	OAuth 2.0 새로 고침 토큰
`GOOGLE_ADS_CUSTOMER_ID`	예*	기본 고객 ID (대시 제외). 도구 호출 시 재정의 가능.
`GOOGLE_ADS_LOGIN_CUSTOMER_ID`	아니요	MCC 액세스를 위한 관리자 계정 ID

사용법

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

도구 참조

도구	설명
`gads_run_gaql`	원시 GAQL 쿼리 실행 — 사용자 지정 보고서를 위한 탈출구
`gads_list_accounts`	액세스 가능한 모든 Google Ads 계정 나열
`gads_account_info`	이름, 통화, 시간대, 관리자 플래그, 상태
`gads_list_campaigns`	상태, 채널 유형, 입찰 전략이 포함된 캠페인
`gads_campaign_performance`	노출수, 클릭수, CTR, CPC, 비용, 전환수, CPA, ROAS
`gads_ad_group_performance`	캠페인 컨텍스트가 포함된 광고 그룹 지표
`gads_keyword_performance`	일치 유형, 품질 점수, 비용, 전환수가 포함된 키워드
`gads_search_terms_report`	광고를 트리거한 실제 사용자 쿼리 — 제외 키워드 및 기회 발견
`gads_conversions_by_campaign`	캠페인별 전환 × 전환 액션
`gads_list_conversion_actions`	카테고리, 유형, 집계 방법이 포함된 모든 전환 액션
`gads_list_rsas`	모든 헤드라인, 설명, 광고 강도, 승인 상태가 포함된 RSA
`gads_rsa_asset_performance`	에셋별 성과 라벨: BEST / GOOD / LOW / PENDING / LEARNING
`gads_list_assets`	계정 에셋: 사이트링크, 콜아웃, 구조화된 스니펫, 이미지
`gads_campaign_assets`	필드 유형과 함께 캠페인에 연결된 에셋
`gads_list_audiences`	규모 및 일치율이 포함된 사용자 목록 (리마케팅, 고객 일치)
`gads_campaign_audience_targeting`	입찰 조정 및 포함/제외가 포함된 캠페인 잠재고객
`gads_geo_performance`	국가, 지역, 도시별 성과
`gads_device_performance`	MOBILE / DESKTOP / TABLET별 비용, 전환수, CPA 구분
`gads_impression_share`	캠페인별 검색 IS, 노출 점유율 손실(예산), 노출 점유율 손실(순위)
`gads_auction_insights`	경쟁사 대비 노출 점유율, 중복 비율, 순위 우위 점유율
`gads_list_budgets`	모든 예산: 금액, 게재 방식, 기간, 권장 예산
`gads_budget_pacing`	활용률 %가 포함된 캠페인별 비용 대 예산

소스에서 빌드

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

라이선스

Available Tools

22 tools

gads_account_infoA

Get basic info for the current Google Ads account: name, currency, timezone, manager flag, status.

Inputs: customer_id.

gads_ad_group_performanceB

Ad group performance with campaign context. Optional campaign_id filter. Default last 28 days, enabled ad groups.

Inputs: start_date, end_date, customer_id, limit, +2 more.

gads_auction_insightsB

Auction Insights report: impression share, overlap rate, outranking share, top-of-page %, and absolute top % vs competitors. Optional campaign filter.

Inputs: customer_id, start_date, end_date, campaign_id.

gads_budget_pacingA

Cost vs budget per campaign for the specified period with utilization percentage. Flags over- and under-pacing campaigns. Default last 28 days.

Inputs: customer_id, start_date, end_date.

gads_campaign_assetsA

Assets linked to campaigns with field type and status. Shows which extensions are active on which campaigns.

Inputs: customer_id, campaign_id.

gads_campaign_audience_targetingA

Audiences attached to campaigns with targeting setting (observation vs targeting) and bid modifier. Shows both inclusion and exclusion lists.

Inputs: customer_id, campaign_id.

gads_campaign_performanceA

Campaign-level performance: impressions, clicks, CTR, avg CPC, cost, conversions, conv value, CPA, ROAS. Defaults to last 28 days, enabled campaigns, sorted by cost desc.

Inputs: start_date, end_date, customer_id, limit, +2 more.

gads_conversions_by_campaignB

Conversions and conversion value broken down by campaign × conversion action. Sorted by conversions desc. Default last 28 days.

Inputs: start_date, end_date, customer_id, limit.

gads_device_performanceA

Clicks, cost, CTR, conversions, and CPA split by MOBILE / DESKTOP / TABLET per campaign. Default last 28 days.

Inputs: customer_id, start_date, end_date, campaign_id.

gads_geo_performanceB

Performance broken down by geographic location (country, region, city). Surfaces top and bottom geo segments by cost and conversions.

Inputs: customer_id, start_date, end_date, campaign_id, +1 more.

gads_impression_shareA

Search Impression Share, Lost IS (Budget), and Lost IS (Rank) per campaign. Identifies whether budget or Quality Score/bid is limiting reach.

Inputs: customer_id, start_date, end_date.

gads_keyword_performanceA

Keyword-level performance with match type, quality score, clicks, cost, conversions. Filter by campaign_id or ad_group_id. Default last 28 days, enabled keywords.

Inputs: start_date, end_date, customer_id, limit, +3 more.

gads_list_accountsA

List all Google Ads customer accounts the authenticated user has access to. Useful for finding customer IDs.

Inputs: no named parameters.

gads_list_assetsB

List account-level assets: sitelinks, callouts, structured snippets, images, call extensions, and more. Filter by asset type.

Inputs: customer_id, asset_type, limit.

gads_list_audiencesB

List user lists (remarketing audiences, customer match lists) in the account with size, eligibility, and match rate.

Inputs: customer_id, limit.

gads_list_budgetsB

All campaign budgets with daily/total amount, delivery method (STANDARD/ACCELERATED), period, and whether a recommended budget exists.

Inputs: customer_id.

gads_list_campaignsB

List campaigns in the account with name, status, channel type, bidding strategy, and date range. Filter by status (default ENABLED).

Inputs: status, customer_id, limit.

gads_list_conversion_actionsC

List all conversion actions configured in the account: name, category, type, whether included in Conversions metric, counting type.

Inputs: customer_id, status.

gads_list_rsasB

List Responsive Search Ads with all headlines, descriptions, Ad Strength rating, and approval status. Filter by campaign or ad group.

Inputs: customer_id, campaign_id, ad_group_id, limit.

gads_rsa_asset_performanceA

Asset-level performance labels (BEST / GOOD / LOW / PENDING / LEARNING) for RSA headlines and descriptions. Identifies which assets to keep, test, or replace.

Inputs: customer_id, ad_group_id, date_range.

gads_run_gaqlA

Escape hatch: run any raw GAQL query against Google Ads. Use when preset tools don't cover the report shape you need. Docs: developers.google.com/google-ads/api/docs/query/overview

Inputs: query (required), customer_id.

gads_search_terms_reportA

Search terms that triggered ads (the actual user queries, not your keywords). Essential for finding wasted spend and negative keyword candidates. Default last 28 days.

Inputs: start_date, end_date, customer_id, limit, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.6/5.0

Scored 2026-04-28 20:20 across 22 tools

Disambiguation5/5

Each tool targets a distinct aspect of Google Ads (account info, campaign performance, keyword performance, asset management, etc.). Even related tools like campaign_performance and ad_group_performance are clearly differentiated by level. No two tools appear to serve the same purpose.

Naming Consistency4/5

All tools share the 'gads_' prefix and use lowercase with underscores. The naming follows a descriptive phrase pattern (e.g., gads_campaign_performance, gads_rsa_asset_performance). While not strictly verb_noun, the convention is consistent and readable.

Tool Count5/5

22 tools is well-scoped for a comprehensive Google Ads server. It covers listing entities, performance reports across dimensions, conversion analysis, budget pacing, auction insights, and an escape hatch. Each tool earns its place without overwhelming the user.

Completeness4/5

The tool set covers most common reporting and listing needs (campaigns, ad groups, keywords, assets, audiences, conversions, etc.). Missing write operations (create/update/delete) but these are often out of scope for a reporting-focused MCP server. The GAQL escape hatch compensates for any missing report shapes.

Maintenance

ActivityInactive

ResponsivenessNo recent community issues

Resources

Related MCP Connectors

Google Ads MCP by AdPlug
io.github.danielpopamd
Google Ads MCP server: 17 tools for reporting, campaigns, keywords, assets. Writes preview first.
Marketing
1
https://api.adplug.app/mcp/google-ads
google-ads
ai.adramp
Google Ads MCP server — manage campaigns, keywords, and metrics.
Marketing E-commerce & Retail
2
https://mcp.adramp.ai
Microsoft Ads MCP by AdPlug
io.github.danielpopamd
Microsoft Ads MCP server: 11 tools for search, PMax, Google Ads imports. Read-only by default.
Marketing
1
https://api.adplug.app/mcp/microsoft-ads
Honeyfield Marketing MCPB
at.honeyfield
Hosted MCP server for marketing agencies: connect Google Ads, GA4, Search Console, Meta, LinkedIn and more to Claude or ChatGPT. Pull reports and make changes via OAuth login, no setup.
Data Platforms Marketing Social Media
3481
https://mcp.ads.honeyfield.at/mcp

Related MCP Servers

PaidSync (Ads analysis &official
Marketing Finance
traffiy
A
license
Not graded
quality
F
maintenance
MCP server for managing Google Ads, Meta Ads, LinkedIn Ads, and TikTok Ads via AI. 210+ tools including account audits, wasted spend detection, and PMax insights.
Updated 6 months ago (2026-05-11 08:14 UTC)
2
MIT
adops-mcp
Marketing AI & Machine Learning Monitoring
automatiabcn
A
license
A
quality
C
maintenance
Cross-platform ad management MCP server for Google Ads and Meta Ads. Campaign analytics, A/B testing with z-test, anomaly detection, and budget reallocation. 15 tools, 60 tests.
Updated 2 months ago (2026-09-13 14:41 UTC)
17
92 npm
MIT
Google Ads MCP Server
bertramdev
A
license
Not graded
quality
D
maintenance
A comprehensive Google Ads MCP server providing ~47 tools for full read/write access to Google Ads accounts, including campaign management, ad creation, keyword management, and reporting.
Updated 8 months ago (2026-03-23 19:27 UTC)
2
Apache 2.0
Google Ads Campaign MCP
Marketing Search
clientskatbi
A
license
Not graded
quality
D
maintenance
MCP server for managing Google Ads campaigns through the official Google Ads API, covering accounts, campaigns, budgets, keywords, search terms, and keyword ideas. It provides tools for both reading and mutating live ads data, such as pausing campaigns, updating budgets, and adding keywords.
Updated 3 months ago (2026-08-09 07:12 UTC)
MIT

google-ads-mcp

이 프로젝트의 존재 이유

예시 프롬프트

데모

기능

사전 요구 사항

환경 변수

사용법

Claude Desktop (claude_desktop_config.json)

Claude Code

Cursor (~/.cursor/mcp.json)

Docker

도구 참조

소스에서 빌드

라이선스

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

PaidSync (Ads analysis &official

adops-mcp

Google Ads MCP Server

Google Ads Campaign MCP

Claude Desktop (`claude_desktop_config.json`)

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