Google Ads Read-Only MCP Server

Safe, read-only access to the Google Ads API (REST v22) for reporting, analysis, and monitoring. No create, update, or delete operations — ideal for dashboards, performance reviews, and auditing.

Note: An official Google Ads MCP also exists at github.com/googleads/google-ads-mcp. This extension provides a focused read-only subset for safe analytics.

Features

• 25 read-only tools — accounts, campaigns, ad groups, ads, keywords, budgets, audiences, extensions, recommendations, and change history
• GAQL queries — run any Google Ads Query Language query for custom data retrieval
• Performance reports — campaign, ad group, ad, keyword, search term, geographic, device, and demographic breakdowns
• Zero production dependencies — pure TypeScript using native fetch
• Safe by design — intentionally excludes all mutating operations

Requirements

• Node.js >= 18
• Google Ads API credentials (setup guide below)

Installation

Claude Code

claude mcp add google-ads-readonly -- npx -y @sebgrosjean/google-ads-readonly@latest

Claude Desktop / Cursor

Add to your MCP config (~/.claude/claude_desktop_config.json or ~/.cursor/mcp.json):

{
  "mcpServers": {
    "google-ads-readonly": {
      "command": "npx",
      "args": ["-y", "@sebgrosjean/google-ads-readonly@latest"],
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "your-developer-token",
        "GOOGLE_ADS_CUSTOMER_ID": "1234567890",
        "GOOGLE_ADS_REFRESH_TOKEN": "your-refresh-token",
        "GOOGLE_ADS_OAUTH_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_ADS_OAUTH_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Claude CoWork (MCPB)

Download google-ads-readonly.mcpb from the latest release and install it in Claude CoWork. No npm or Node.js setup required.

From Source

git clone https://github.com/ZenCocoon/google-ads-readonly.git
cd google-ads-readonly && npm install && npm run build
GOOGLE_ADS_DEVELOPER_TOKEN="..." GOOGLE_ADS_CUSTOMER_ID="..." \
  GOOGLE_ADS_REFRESH_TOKEN="..." GOOGLE_ADS_OAUTH_CLIENT_ID="..." GOOGLE_ADS_OAUTH_CLIENT_SECRET="..." \
  node dist/mcp-bundled.js

Getting Google Ads API Credentials

You need five values. Setup takes about 5 minutes. The server auto-refreshes access tokens — no manual token renewal needed.

1. Developer Token

1. Sign in to your Google Ads Manager Account
2. Go to Tools & Settings > API Center (ads.google.com/aw/apicenter)
3. Copy your developer token

Your token starts with Test Access (test accounts only). To read production accounts, apply for Basic Access from the same page — this is typically approved quickly for read-only use.

2. OAuth2 Client ID & Secret

1. Go to Google Cloud Console > Credentials
2. Create a project (or use an existing one)
3. Enable the Google Ads API: console.cloud.google.com/apis/library/googleads.googleapis.com
4. Click + CREATE CREDENTIALS > OAuth client ID
   • If prompted, configure the OAuth consent screen first (External, fill in app name + your email)
   • Application type: Web application
   • Add https://developers.google.com/oauthplayground as an Authorized redirect URI
5. Copy your Client ID and Client Secret

3. Refresh Token

1. Go to developers.google.com/oauthplayground
2. Click the gear icon (top right), check "Use your own OAuth credentials"
3. Enter your Client ID and Client Secret
4. In Step 1, type https://www.googleapis.com/auth/adwords in the input box and click Authorize APIs
5. Sign in with the Google account that has Google Ads access
6. In Step 2, click Exchange authorization code for tokens
7. Copy the Refresh Token (this doesn't expire — the server auto-refreshes access tokens from it)

4. Customer ID

Your 10-digit Google Ads customer ID, visible in the top-right corner of ads.google.com (e.g., 123-456-7890). Enter it without dashes: 1234567890.

Optional: Login Customer ID

If you access accounts through a Manager (MCC) account, also set GOOGLE_ADS_LOGIN_CUSTOMER_ID to your manager account's customer ID.

MCP Tools

Account & Query

| Tool | Description | |------|-------------| | gads_list_accounts | List all accessible customer accounts | | gads_get_account | Get account details (name, currency, timezone) | | gads_query | Run any GAQL query — the most powerful tool for custom data retrieval |

Campaigns & Budgets

| Tool | Description | |------|-------------| | gads_list_campaigns | List campaigns with metrics (filterable by status) | | gads_get_campaign | Get campaign details with network settings and metrics | | gads_list_budgets | List campaign budgets |

Ad Groups & Ads

| Tool | Description | |------|-------------| | gads_list_ad_groups | List ad groups (filterable by campaign) | | gads_get_ad_group | Get ad group details with performance | | gads_list_ads | List ads (filterable by ad group) | | gads_get_ad | Get ad details (headlines, descriptions, performance) |

Keywords

| Tool | Description | |------|-------------| | gads_list_keywords | List keywords with match types, quality scores, and metrics | | gads_get_keyword_ideas | Generate keyword suggestions from seed keywords or URLs |

Performance Reports

| Tool | Description | |------|-------------| | gads_campaign_performance | Campaign performance (impressions, clicks, CTR, CPC, conversions) | | gads_ad_group_performance | Ad group performance | | gads_ad_performance | Ad-level performance | | gads_keyword_performance | Keyword performance with quality scores | | gads_search_term_report | Actual search queries that triggered your ads | | gads_geo_report | Geographic performance breakdown | | gads_device_report | Device breakdown (desktop, mobile, tablet) | | gads_age_gender_report | Demographic breakdown |

All performance reports support date_range presets (LAST_7_DAYS, LAST_30_DAYS, etc.) or custom start_date/end_date ranges.

Audiences & Extensions

| Tool | Description | |------|-------------| | gads_list_audiences | List audience segments with performance | | gads_list_remarketing_lists | List remarketing/user lists | | gads_list_extensions | List ad extensions (sitelinks, callouts, etc.) |

Recommendations & History

| Tool | Description | |------|-------------| | gads_list_recommendations | Google's optimization recommendations | | gads_get_change_history | Audit who changed what and when |

License

MIT