Provides comprehensive tools for managing Google Ads campaigns through the Google Ads API, including GAQL query execution with pagination, performance data retrieval with filtering and currency conversion, resource discovery, and account management with GCloud/ADC authentication support.
Google Ads MCP
Google Ads MCP server with GCloud/ADC auth.
Contents
Prerequisites
- A GCP project with the Google Ads API enabled.
- Ensure the credentials you use (user/ADC or service account) have the Service Usage Consumer role on that project (grants
serviceusage.services.use
). This is granted to the account, not the project by default. - A Google Ads Developer Token is required:
- Docs: https://developers.google.com/google-ads/api/docs/get-started/dev-token
- Application form: https://support.google.com/adspolicy/contact/new_token_application
Quick Start
- Package manager: pnpm recommended (pnpm-lock.yaml committed). npm also works.
- Install:
pnpm install && pnpm build
(ornpm install && npm run build
) - Run (dev):
pnpm dev
(stdio transport) - Run (built):
node dist/cli.js
MCP Clients
- Claude Desktop (JSON settings)
- Add this to your Claude Desktop settings JSON:
- CLI usage
node dist/cli.js
uses stdio transport. Point your MCP client to this command.
- Cursor (MCP JSON)
- Paste into Cursor’s MCP JSON (see docs: https://docs.cursor.com/en/context/mcp#using-mcp-json):
Auth Options
- Preferred: ADC via gcloud CLI
- Install gcloud and run:
gcloud auth application-default login --scopes=https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/adwords
- Install gcloud and run:
- ADC is the default auth path; no special env flag required.
- Note: If you already have an ADC file (authorized_user JSON), point to it with
GOOGLE_APPLICATION_CREDENTIALS=/path/to/adc.json
.
- Note: If you already have an ADC file (authorized_user JSON), point to it with
- Optional CLI token fallback: set
GOOGLE_ADS_GCLOUD_USE_CLI=true
- Other modes (raw OAuth client JSON, service accounts) are not supported here. Google Ads requires user OAuth; service accounts are generally not accepted.
Existing ADC File (no gcloud)
- If you already have an
authorized_user
ADC JSON:- Set
GOOGLE_APPLICATION_CREDENTIALS=/absolute/path/to/adc.json
. - Or place it at
.auth/adc.json
in this project; startup auto-detects it.
- Set
Optional: OAuth Client (no gcloud)
- If you cannot install gcloud, you can complete OAuth via device flow and create an ADC file locally.
- Set env vars to your Desktop-app OAuth client:
GOOGLE_OAUTH_CLIENT_ID=...
GOOGLE_OAUTH_CLIENT_SECRET=...
- Prompt your LLM to run the tool action:
manage_auth
with{ "action": "oauth_login" }
- This will:
- Prompt you to open a URL and enter a code.
- Save an ADC
authorized_user
JSON at.auth/adc.json
(0600 perms). - Set
GOOGLE_APPLICATION_CREDENTIALS
in-process and verify Ads scope. - Next startups auto-detect
.auth/adc.json
, so you usually don’t need to export anything.
Tools
Note: You don’t run tool payloads yourself — your MCP client’s LLM calls tools. Use natural prompts (for example: “Check my Google Ads auth status”) and the client will invoke the right tool. JSON shown below is for integrators building custom clients.
- manage_auth
- Purpose: Inspect and manage auth. Always safe to run with default action
status
. - Inputs:
action
:status
|switch
|refresh
(defaultstatus
)config_name
: gcloud config name (forswitch
)allow_subprocess
: boolean (default true). Set tofalse
to only print commands (no execution).
- Output: Text summary including env values, ADC probe, Ads scope check, accessible accounts count. For
switch
/refresh
, executesgcloud
by default (or prints commands ifallow_subprocess=false
). - Behavior: If gcloud is not found on PATH, the tool falls back to printing the exact commands and an install link. If
GOOGLE_OAUTH_CLIENT_ID/SECRET
are present, use{ "action": "oauth_login" }
to complete OAuth locally and create an ADC file. - Example (status):
{ "action": "status" }
- Example (print steps, don’t run):
{ "action": "refresh" }
- Example (execute):
{ "action": "switch", "config_name": "work", "allow_subprocess": true }
- How to ask your MCP client:
- “Check Google Ads auth status.”
- “Refresh ADC auth for Google Ads (open login).”
- “Switch gcloud config to ‘work’ and refresh ADC.”
- “Create local ADC via OAuth using my client ID/secret.”
- Purpose: Inspect and manage auth. Always safe to run with default action
- list_resources
- Purpose: Discover GAQL FROM resources or list accessible accounts.
- Inputs:
kind
:resources
|accounts
(defaultresources
)filter
: substring for resource names (whenresources
)limit
: 1–1000 (default 500)output_format
:table
|json
|csv
(defaulttable
)
- Notes: Uses
google_ads_field
metadata for resources (no FROM clause). Accounts come fromcustomers:listAccessibleCustomers
. - Example (resources):
{ "kind": "resources", "filter": "campaign", "limit": 50 }
- Example (accounts):
{ "kind": "accounts", "output_format": "table" }
- How to ask your MCP client:
- “List GAQL FROM resources containing ‘campaign’ (limit 50).”
- “List my accessible Google Ads accounts.”
- execute_gaql_query
- Purpose: Run raw GAQL with optional pagination.
- Inputs:
customer_id
(optional). If omitted, tool prompts you to pick one from accessible accounts.query
: GAQL string- Paging:
page_size
,page_token
,auto_paginate
(bool),max_pages
(1–20) output_format
:table
|json
|csv
(defaulttable
)
- Output: Table/JSON/CSV of results. Shows
Next Page Token
when not auto-paginating. - How to ask your MCP client:
- “Run GAQL on 1234567890: SELECT campaign.id, metrics.clicks FROM campaign WHERE segments.date DURING LAST_30_DAYS LIMIT 10.”
- “Run that query and give me CSV.”
- Example:
- get_performance
- Purpose: Quick performance by level with common filters.
- Inputs:
customer_id
(optional). If omitted, tool lists accessible accounts to choose from.level
:account
|campaign
|ad_group
|ad
days
: 1–365 (default 30)limit
: 1–1000 (default 50)- Paging:
page_size
,page_token
,auto_paginate
,max_pages
output_format
:table
|json
|csv
(defaulttable
)filters
(optional):status
(e.g., ENABLED)nameContains
(entity name contains)campaignNameContains
(ignored ataccount
level)minClicks
,minImpressions
- Output: Includes
customer.currency_code
and computedmetrics.cost_units
. - How to ask your MCP client:
- “Show account-level performance for 1234567890 (last 30 days).”
- “Show campaign performance, only ENABLED, min 10 clicks.”
- Examples:
- Account (last 30 days):
{ "customer_id": "1234567890", "level": "account" }
- Campaigns filtered:
{ "level": "campaign", "filters": { "status": "ENABLED", "minClicks": 10 } }
- Account (last 30 days):
- gaql_help
- Purpose: Provide GAQL guidance using an offline-first cheat sheet plus best-effort official docs.
- Defaults:
- Offline-first hybrid behavior. Includes
docs/gaql.md
and, when reachable, pulls relevant snippets from official GAQL docs. - No environment configuration required; the LLM can steer with inputs only.
- Offline-first hybrid behavior. Includes
- Inputs:
question
(free text)topics
: subset of[overview, grammar, structure, date_ranges, case_sensitivity, ordering, cookbook]
quick_tips
: boolean (defaultfalse
). Whentrue
, returns a concise offline tips list only.include_examples
: boolean (biases toward code blocks and increases returned snippet count)max_chars
: 400–8000 (default ~1800; may expand slightly wheninclude_examples=true
)
- Output:
- “Sources” section listing
docs/gaql.md
and any official docs used, followed by condensed, high-signal snippets.
- “Sources” section listing
- How to ask your MCP client:
- “Give me GAQL quick tips.”
- “GAQL help on date ranges and ordering with examples.”
- Examples:
- Quick tips only:
{ "quick_tips": true }
- Focused help:
{ "question": "date ranges and ordering", "topics": ["date_ranges", "ordering"], "include_examples": true }
- Quick tips only:
Env Vars
- Required
GOOGLE_ADS_DEVELOPER_TOKEN
— your Google Ads developer token
- Recommended
- Optional
GOOGLE_APPLICATION_CREDENTIALS
— path to an ADC authorized_user JSON (or place file at.auth/adc.json
)GOOGLE_OAUTH_CLIENT_ID
,GOOGLE_OAUTH_CLIENT_SECRET
— enablesmanage_auth { action: "oauth_login" }
(device flow) to create.auth/adc.json
GOOGLE_ADS_ACCOUNT_ID
— default 10-digit account IDGOOGLE_ADS_MANAGER_ACCOUNT_ID
— manager account ID (MCC) when acting through a managerGOOGLE_ADS_API_VERSION
— defaultv19
- Note:
gaql_help
does not require any env flags; it runs with a sensible offline-first default and lists its sources. GOOGLE_ADS_ACCESS_TOKEN
— dev/test override token (bypasses ADC)
Development
npm run dev
— run from TS viatsx
npm run build
— emit ESM todist/
npm start
— run compiled CLInpm run typecheck
,npm run lint
,npm run test
Testing
- Unit tests (fast, mocked):
pnpm test
orpnpm run test:unit
- Integration tests (real API, read-only):
- Prereqs: ADC login (
gcloud auth application-default login --scopes=https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/adwords
) andGOOGLE_ADS_DEVELOPER_TOKEN
set - Optional:
GOOGLE_ADS_MANAGER_ACCOUNT_ID
(MCC login-customer),GOOGLE_ADS_ACCOUNT_ID
(target account) - Run:
pnpm run test:integration
- Notes: Queries use small
LIMIT
s and short date ranges to minimize quota usage
- Prereqs: ADC login (
License
MIT
This server cannot be installed
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Enables interaction with Google Ads through the Google Ads API using GCloud authentication. Supports GAQL query execution, performance data retrieval, account management, and resource discovery with pagination and multiple output formats.