Google Ads MCP Server

A comprehensive Google Ads MCP server providing ~47 tools for full read/write access to Google Ads accounts. Built for Claude Desktop, Claude Code, and other MCP-compatible clients.

Features

• Accounts — list accessible accounts, get account info, MCC hierarchy
• Campaigns — full CRUD for Search, Display, Video, Demand Gen campaigns
• Ad Groups — create, update, list, and manage ad groups
• Ads — RSA, Responsive Display, Video, and Demand Gen ad creation
• Keywords — add, remove, update bids, get performance
• Performance Max — complete PMax support: asset groups, assets, audience signals
• Budgets — create, update, list, and check utilization
• Reporting — flexible GAQL queries, campaign/ad group/keyword performance
• Utilities — GAQL resource discovery, field metadata, micros conversion

Setup

Prerequisites

• Python 3.12+
• uv for dependency management
• Google Ads API credentials (developer token, GCP service account JSON key)

Installation

git clone https://github.com/bertramdev/GoogleAdsMCP.git
cd GoogleAdsMCP
uv sync

Configuration

Copy .env.example to .env and fill in your credentials:

cp .env.example .env

Required environment variables:

• GOOGLE_ADS_DEVELOPER_TOKEN — your API developer token
• GOOGLE_ADS_SERVICE_ACCOUNT_PATH — path to GCP service account JSON key file
• GOOGLE_ADS_LOGIN_CUSTOMER_ID — MCC customer ID (if using MCC)

Optional:

• GOOGLE_ADS_IMPERSONATED_EMAIL — Workspace user email for domain-wide delegation
• GOOGLE_ADS_CUSTOMER_ID — default customer ID for operations

Running

uv run google-ads-mcp

Claude Desktop Configuration

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "google-ads": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/GoogleAdsMCP", "google-ads-mcp"],
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "...",
        "GOOGLE_ADS_SERVICE_ACCOUNT_PATH": "/path/to/service-account.json",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "...",
        "GOOGLE_ADS_IMPERSONATED_EMAIL": "user@yourdomain.com"
      }
    }
  }
}

Claude Code Configuration

Add to .mcp.json in the project root:

{
  "mcpServers": {
    "google-ads": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/GoogleAdsMCP", "google-ads-mcp"],
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "...",
        "GOOGLE_ADS_SERVICE_ACCOUNT_PATH": "/path/to/service-account.json",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "...",
        "GOOGLE_ADS_IMPERSONATED_EMAIL": "user@yourdomain.com"
      }
    }
  }
}

Permissions

All tools include MCP tool annotations (readOnlyHint, destructiveHint, etc.) so clients can make informed permission decisions. However, Claude Code requires explicit allow rules — annotations alone don't auto-approve tools.

Within this project: The project-level .claude/settings.json auto-allows read-only tools (get_*, list_*, execute_gaql, convert_micros). Write tools require approval on each use.

From other projects: Project-level permissions don't apply. To allow all tools globally, add to ~/.claude/settings.json:

{
  "permissions": {
    "allow": [
      "mcp__google-ads__*"
    ]
  }
}

Or for read-only tools only:

{
  "permissions": {
    "allow": [
      "mcp__google-ads__get_*",
      "mcp__google-ads__list_*",
      "mcp__google-ads__execute_gaql",
      "mcp__google-ads__convert_micros"
    ]
  }
}

Security Considerations

This MCP server cannot modify account access, user permissions, login credentials, billing, or payment methods. There are no tools for account administration — a compromised server cannot lock anyone out of their account.

Worst-case impact if credentials are compromised:

Risk	Details
Financial	Creating campaigns/budgets or increasing keyword bids could spend money
Disruption	Pausing/removing campaigns, keywords, or ad groups
Data exposure	Reading account performance, search terms, and campaign details. execute_gaql can also read sensitive resources like customer_user_access and billing_setup (read-only — no mutations possible via GAQL)

Removal tools (remove_campaign, remove_keyword, remove_asset_from_group) require confirm_removal=True as a server-side safety guard. The set_*_status tools execute immediately without a confirmation parameter.

Testing

uv run pytest

Tool Reference (47 tools)

Accounts (3)

• list_accessible_accounts — List accounts accessible via credentials
• get_account_info — Account details (name, currency, timezone)
• get_account_hierarchy — MCC hierarchy tree

Campaigns (6)

• list_campaigns — List campaigns with optional status filter
• get_campaign — Single campaign details
• create_campaign — Create Search/Display campaign with budget
• update_campaign — Update name, bidding strategy, etc.
• set_campaign_status — Enable/pause/remove
• remove_campaign — Soft delete with confirm

Ad Groups (5)

• list_ad_groups — List ad groups in campaign
• get_ad_group — Ad group details
• create_ad_group — Create ad group with bid
• update_ad_group — Update name, bid, status
• set_ad_group_status — Enable/pause/remove

Ads (7)

• list_ads — List ads in ad group
• create_responsive_search_ad — RSA for Search campaigns
• create_responsive_display_ad — Responsive display ad
• create_video_ad — Video ad for YouTube
• create_demand_gen_ad — Demand Gen ad
• set_ad_status — Enable/pause/remove
• get_ad_details — Full ad details

Keywords (5)

• list_keywords — List keywords in ad group
• add_keywords — Add keywords with match types (batch)
• remove_keyword — Remove keyword
• update_keyword_bid — Update CPC bid
• get_keyword_performance — Keyword metrics

Performance Max (8)

• create_performance_max_campaign — Full PMax campaign creation
• list_asset_groups — List asset groups in PMax campaign
• get_asset_group_details — Asset group details with linked assets
• add_assets_to_group — Add assets to asset group
• remove_asset_from_group — Remove asset from asset group
• add_audience_signal — Add audience/search theme signals
• get_asset_performance — Asset-level performance labels
• get_pmax_placement_performance — Channel breakdown

Budgets (4)

• list_budgets — List campaign budgets
• create_budget — Create shared budget
• update_budget — Update budget amount
• get_budget_utilization — Budget vs actual spend

Reporting (6)

• execute_gaql — Flexible GAQL query execution
• get_campaign_performance — Campaign metrics
• get_ad_group_performance — Ad group metrics
• get_search_terms_report — Search terms report
• get_keyword_performance_report — Keyword metrics
• get_account_performance_summary — Account daily summary

Utilities (3)

• list_gaql_resources — Available GAQL resources
• get_field_metadata — Field metadata for a resource
• convert_micros — Micros to currency conversion

License

Apache 2.0 — see LICENSE.