Google Ads MCP Server 🚀

A powerful MCP server that bridges LLMs with the Google Ads API — 143 tools for querying, managing, and optimizing your ad accounts through natural language.

Targets Google Ads API 25.2 using the v25 endpoint and Python SDK 33. New fields and enums use the existing query tools and strict native resource requests. Dedicated tools cover lifecycle goals, lift studies, planning, PMax draft conversion, video crawl, URL options and synthetic attestations. See the migration coverage report for breaking changes, validation, and the upstream vertical_ads_item_bid gap.

Ask Claude or Gemini to "show me my top campaigns this month" or "pause that underperforming ad group" — and it just works.

This is not an officially supported Google product.

✨ Features

• 📊 Full GAQL Support — Run any Google Ads Query Language query with automatic field formatting
• 🔧 143 Tools — Read, write, and manage campaigns, ad groups, ads, keywords, labels, budgets, audiences, and more
• 📖 Built-in Docs — GAQL syntax reference, reporting field docs, resource metadata, and a tool guide available as tools
• 🌐 Live Release Notes — Access current Google Ads API release notes as an MCP resource
• 🔍 Smart Tool Search — BM25-powered tool discovery surfaces relevant tools automatically
• 🔒 Mutation Safety — Mutation tools are hidden by default; unlock them per-session when needed
• 📊 Curated Reporting — Device, geographic, impression share, quality scores, conversion goals, search terms, Shopping/cart data, landing pages, audience expansion, video, and placement diagnostics
• 📄 Complete, Token-Safe Delivery — Variable-size reads use stable snapshot pagination or exact CSV artifacts; 100-row previews reserve separate budgets for source rows, shared derived sections, and the complete response without capping Google data
• ⚡ Snapshot Correctness — A tokenless read starts fresh, while explicit continuation and export tokens keep the original credential-scoped snapshot stable
• 🛡️ Hardened Inputs — Enum, ID, and date filters are normalized and validated up front so bad inputs fail fast with clear messages
• 📥 CSV Export — Export any GAQL query to CSV for bulk extraction and downstream analysis
• 📈 Optimization — Recommendations, optimization score, bid/budget simulations, and search term analysis
• 🏎️ Performance Max — Asset diagnostics, top combinations, and placement insights
• 🔑 Keyword Research — Generate keyword ideas with search volume and competition data
• 🏷️ Label Management — Create, apply, and remove labels across campaigns and ad groups
• 👥 Audience Creation — Build modern AudienceService audience resources with include/exclude logic
• 🚫 Negative Keywords — Full shared set and campaign-level negative keyword management
• 💡 Smart Campaigns — Get AI-suggested keyword themes, ad copy, and budget recommendations
• 📤 Conversion Uploads — Upload offline click and call conversions with partial failure handling
• 🩺 Offline Upload Diagnostics — Monitor account- and conversion-action-level upload health, alerts, daily summaries, and job summaries
• 🖥️ Works Everywhere — Claude Code, Claude Desktop, Gemini CLI, or any MCP client

📋 Available Tools (143)

API 25.2 workflows

Tools	Purpose
mutate_ads_resources, get_resource_mutation_schema	Strict native resource changes, including new conversion types, conversion value rules, Demand Gen automation and attribution partners; validates by default
mutate_goals, mutate_campaign_goal_configs	Unified new-customer, retention and loyalty goals; validates by default
update_asset_group_url_options, update_campaign_video_crawl_settings	PMax URL and crawl settings; validates by default
update_ad_synthetic_content_info, update_asset_synthetic_content_info	Advertiser attestations; validates by default
generate_pmax_draft_campaign	Validate Smart-to-PMax conversion or create a paused, incomplete draft
list_lift_measurements	Study configuration, brand lift and conversion lift across supported dimensions
get_planning_request_schema	Exact installed schemas for the planning tools below
list_benchmarks_available_dates, list_benchmarks_sources, list_benchmarks_locations, list_benchmarks_products, generate_benchmarks_metrics	Benchmark categories, aggregate/share/percentile data and availability
generate_creator_insights, generate_trending_insights, list_audience_insights_attributes	Handles, topics, sentiment, consent-gated creator data and capability discovery
generate_reach_forecast, list_plannable_products, list_plannable_locations	Reach plans with parental status, multiple locations and current frequency caps
fetch_incentives, apply_incentive, create_product_link_invitation, get_account_service_request_schema	Current incentive and invitation schemas; redemption and invitation apply directly because these services have no validate-only mode

get_campaign_settings now returns campaign_goal_configs, conversion-owner account_goals and goal_owner_customer_id. The removed lifecycle keys and resources cannot be used in v25. Incompatible reporting combinations state omitted_metrics; unavailable benchmark metrics are left absent.

🔍 Query & Discovery

Tool	Description
execute_gaql	Run GAQL with required-SELECT repairs, actionable errors, and explicit change-event retention policy
export_gaql_csv	Export GAQL or an exact snapshot to CSV, preserving query adjustments and history coverage
export_materialized_response_csv	Explicitly write an exact deferred oversized read response returned by another tool
list_accessible_accounts	Page through a short-lived, exact in-memory snapshot of accessible accounts without writing files
export_accessible_accounts_csv	Explicitly export the exact accessible-account snapshot to CSV

list_accessible_accounts now returns a pagination envelope with accounts, counts, continuation metadata, and an explicit export call instead of the legacy bare list. This keeps account discovery read-only while making every accessible account available without an unbounded model response.

execute_gaql caps inline rows at 32 KiB and the logical response at 48 KiB. max_rows limits only the preview; bulk_export_call preserves all retrieved rows without rerunning the query. Query LIMIT and API restrictions still apply. MCP can serialize the result as both text and structured content, so the transport envelope can exceed the logical-response budget.

📖 Docs & Tool Guidance

Tool	Description
get_tool_guide	Compact map of tools and when to use them
get_gaql_doc	Compact GAQL syntax reference
get_resource_metadata	Selectable, filterable, and sortable fields for a GAQL resource
get_reporting_view_doc	Reporting view names or detailed view metadata
get_reporting_fields_doc	Detailed docs for specific reporting query fields
search_google_ads_fields	Live field metadata search by raw query or multiple safe name patterns
export_google_ads_fields_csv	Export every matching live field-metadata row and requested column

🔒 Session Controls

Tool	Description
get_tool_visibility_profile	Check whether mutation tools are unlocked
unlock_mutation_tools	Reveal mutation tools for the current session
lock_mutation_tools	Hide mutation tools for the current session

📈 Optimization & Recommendations

Tool	Description
get_optimization_score_summary	Account optimization score and uplift by type
list_recommendations	Open recommendations filtered by type or campaign
apply_recommendations	Apply existing recommendations
dismiss_recommendations	Dismiss existing recommendations
list_recommendation_subscriptions	Current recommendation auto-apply subscriptions
create_recommendation_subscription	Create a paused or enabled subscription
set_recommendation_subscription_status	Pause or enable a subscription

🔎 Search Terms

Tool	Description
list_campaign_search_term_insights	Insight categories and search terms for a single campaign
list_customer_search_term_insights	Account-level insight categories and search terms
analyze_search_terms	Heuristic exact-match and negative keyword candidates
compare_search_terms	Compare search-term performance between two date windows

📊 Simulations

Tool	Description
list_campaign_simulations	Campaign-level bid/budget simulations with supported point lists by default
list_ad_group_simulations	Ad-group-level simulations with supported point lists by default
list_ad_group_criterion_simulations	Keyword-level CPC bid simulations

🕐 Change History

Tool	Description
list_change_statuses	Changed resources and last change timestamps
list_change_events	Granular changes with typed filters, inclusive relative lookback, and opt-in clamping for explicit dates
export_change_history_csv	Export maximum retrievable change data: daily status slices across 90 days plus a 30-day granular event overlay
get_change_history_extended	Preview explicit dates, or 90-day latest-status data plus the 30-day event overlay when dates are omitted

🏎️ Performance Max

Tool	Description
list_asset_group_assets	Asset links and serving diagnostics
list_asset_group_top_combinations	Top served asset combinations
list_performance_max_placements	Placement names and impression counts

📊 Reporting

Tool	Description
get_campaign_performance	Core campaign performance with optional DATE/WEEK/MONTH/DEVICE/NETWORK segments
analyze_customer_acquisition_performance	New-versus-returning conversion performance joined to total campaign traffic and cost through compatible split queries
get_demographic_performance	Age, gender, and income performance bundled into a single response
get_landing_page_performance	Top landing pages with compact cost and conversion metrics
get_ad_inventory	Ad creative inventory with optional recent performance
get_competitive_pressure_report	Bundled impression-share pressure, auction insights, and change history
list_device_performance	Campaign performance segmented by device
list_geographic_performance	Campaign performance by geography with API-resolved country names
list_impression_share	Campaign impression share metrics
get_campaign_conversion_goals	Conversion goals and custom goal config for a campaign
get_campaign_settings	Campaign settings, budgets, location names, shared lists, conversion goals, and lifecycle goals in one snapshot
compare_performance_periods	Compare explicit nonoverlapping date windows with complete summed metrics and optional DEVICE or physical-user COUNTRY breakdown
compare_performance_around_changes	Compare complete retained daily periods around supported campaign/budget change evidence, excluding boundary days
list_keyword_quality_scores	Keyword quality score diagnostics
summarize_keyword_quality_scores	Quality score distribution summary across campaigns
list_rsa_ad_strength	RSA ad strength diagnostics
list_conversion_actions	Conversion action configuration
list_audience_performance	Audience performance at campaign or ad group scope
list_video_enhancements	Video Enhancement rows with source, duration, and video-view metrics
summarize_cart_data_sales	Compact cart-data revenue, profit, units-sold, and lead/cross-sell summary
compare_biddable_vs_all_cart_value	Compare biddable cart metrics with all cart metrics
list_cart_profit_outliers	Highest or lowest cart-data profit outliers
list_shopping_attribution_breakdown	Shopping performance split by conversion attribution event type
list_campaign_view_through_optimization	Campaign view-through conversion optimization settings
list_video_audibility_performance	Video audibility and watch-time diagnostics
list_vertical_ads_performance	Vertical ads performance by listing, brand, location, partner account, or vertical
list_campaign_search_terms	Campaign-level search terms with compact cost and conversion metrics
list_ai_max_search_term_ad_combinations	AI Max search term, headline, and landing-page combinations
list_final_url_expansion_assets	Final URL expansion landing pages with recent performance
list_targeting_expansion_performance	Automated targeting expansion performance by campaign and ad group
list_content_suitability_placements	Grouped or detailed content-suitability placement impressions
list_location_interest_performance	Location-interest performance for geo optimization
summarize_shopping_product_status	Compact Shopping product eligibility and issue distribution
list_shopping_product_status	Shopping product status, issues, and recent performance rows
list_travel_feed_asset_sets	Travel feed asset set configuration and linked feed IDs
list_retail_filter_shared_criteria	Tag-based retail filter shared criteria

compare_performance_periods(customer_id, campaign_id, periods, segment_by=None, login_customer_id=None) accepts nonoverlapping inclusive account-local dates. COUNTRY uses physical-user location and API-resolved names; geographic totals can differ from campaign totals. compare_performance_around_changes(customer_id, campaign_id, start_date, end_date, segment_by=None, login_customer_id=None) requires complete days within retained granular history. It excludes every supported boundary day and disables comparison if change reads reach their cap. Current budget links alone do not prove historical association. Neither report establishes causal effects, edits inside portfolio strategies, or historical conversion-goal switches.

📢 Campaign Management

Tool	Description
set_campaign_status	Set a campaign to PAUSED or ENABLED
update_campaign_budget	Change a campaign's daily budget
update_campaign_targeting_setting	Replace campaign targeting restrictions such as AUDIENCE, KEYWORD, or PLACEMENT
add_campaign_location_targets	Add geo_target_ids as targets or exclusions using required negative, with optional validate_only and partial_failure
remove_campaign_location_targets	Verify and remove campaign LOCATION criterion_ids, with optional validate_only and partial_failure
set_campaign_view_through_conversion_optimization	Enable or disable view-through conversion optimization
add_campaign_audiences	Add supported campaign audience criteria with partial failure handling
remove_campaign_audiences	Remove campaign audience criteria by criterion ID
list_campaign_audiences	List campaign-level audience criteria with copy-ready resource names
diff_campaign_audiences	Compare two campaigns' audiences and return copy-ready differences
copy_audiences_between_campaigns	Copy missing audiences from a source campaign to a target (dry-run by default)

Location removals take attachment criterion IDs from get_campaign_settings, not geo target IDs. Additions require negative=false for targets or true for exclusions. Both tools validate inputs and retain mutation visibility rules.

👥 Audience Management

Tool	Description
create_audience	Create a modern audience resource with AND/OR include logic and optional user-list exclusions
search_user_interests	Search user-interest taxonomy nodes (AFFINITY, IN_MARKET, etc.) for audience targeting
summarize_customer_match_jobs	Complete available job counts by list name, status, match-rate bucket, and failure reason, with highest-ID previews and exact exports

summarize_customer_match_jobs(customer_id, user_list_ids=None, jobs_per_list=5, login_customer_id=None) counts all matching jobs before selecting previews. v25.2 exposes no Customer Match creation/upload timestamp, so highest numeric IDs are a labeled recency heuristic. Match-rate buckets are not exact or volume-weighted rates. Offline conversion upload health uses the separate upload summary tools. Large summaries have a 32 KiB logical-response budget and exact deferred export; the source CSV includes every retrieved job.

Note: create_audience creates the modern audience resource, not legacy combined_audience rows. The current campaign attachment tool still targets the campaign criterion types exposed by CampaignCriterion, so it does not accept type="AUDIENCE".

👥 Ad Group Management

Tool	Description
set_ad_group_status	Set an ad group to PAUSED or ENABLED
set_ad_group_criterion_status	Set ad-group criteria such as USER_LIST audiences to PAUSED or ENABLED
remove_ad_group_audiences	Remove ad-group audience criteria by criterion ID
update_ad_group_bid	Update an ad group's CPC bid

📝 Ad Management

Tool	Description
set_ad_status	Set an ad to PAUSED or ENABLED

🔑 Keyword Management

Tool	Description
set_keyword_status	Set a keyword to PAUSED or ENABLED
update_keyword_bid	Update a keyword's CPC bid
generate_keyword_ideas	Research new keywords with volume & competition data

🚫 Negative Keywords

Tool	Description
list_shared_sets	List negative keyword shared sets
create_shared_set	Create a new shared negative keyword set
delete_shared_set	Delete a shared set
list_shared_set_keywords	List keywords in a shared set
add_shared_set_keywords	Add keywords to a shared set
remove_shared_set_keywords	Remove keywords from a shared set
list_campaign_shared_sets	List shared sets attached to a campaign
attach_shared_set_to_campaign	Attach a shared set to a campaign
detach_shared_set_from_campaign	Detach a shared set from a campaign
list_campaign_negative_keywords	List campaign-level negative keywords
add_campaign_negative_keywords	Add campaign-level negative keywords
remove_campaign_negative_keywords	Remove campaign-level negative keywords

🏷️ Labels

Tool	Description
create_label	Create a new label
delete_label	Delete a label
manage_campaign_labels	Apply or remove a label to/from campaigns
manage_ad_group_labels	Apply or remove a label to/from ad groups

💡 Smart Campaign Suggestions

Tool	Description
suggest_keyword_themes	Get keyword theme suggestions for a business
suggest_smart_campaign_ad	Get AI-suggested headlines and descriptions
suggest_smart_campaign_budget	Get low/recommended/high budget options

📤 Conversion Uploads & Diagnostics

Tool	Description
list_offline_conversion_upload_client_summaries	Account-level offline upload diagnostics grouped by import client
list_offline_conversion_upload_conversion_action_summaries	Conversion-action-level offline upload diagnostics with recent job and daily summaries
upload_click_conversions	Upload offline click conversions (gclid/gbraid/wbraid)
upload_call_conversions	Upload offline call conversions

🚀 Quick Start

Prerequisites

• Python 3.12+
• uv (recommended) or pipx
• A google-ads.yaml file with your Google Ads API credentials

1. Get Your Credentials

You need a google-ads.yaml with these keys:

client_id: YOUR_CLIENT_ID
client_secret: YOUR_CLIENT_SECRET
refresh_token: YOUR_REFRESH_TOKEN
developer_token: YOUR_DEVELOPER_TOKEN
login_customer_id: YOUR_MCC_ID  # optional but recommended

Don't have one? Generate it using the authentication example from the google-ads-python library.

2. Install & Run

Option A: Claude Code (recommended)

The run-mcp-server script uses the stdio transport expected by Claude Code.

# Install from repo
claude mcp add --transport stdio GoogleAds \
  --env GOOGLE_ADS_CREDENTIALS=PATH_TO_YAML \
  -- pipx run --spec git+https://github.com/jeffreywlai/google_ads_mcp.git run-mcp-server

Or from a local clone:

claude mcp add --transport stdio GoogleAds \
  --env GOOGLE_ADS_CREDENTIALS=PATH_TO_YAML \
  -- uv run --directory /path/to/google_ads_mcp -m ads_mcp.stdio

Type /mcp in Claude Code to verify it's connected.

Option B: Gemini CLI

Add to your Gemini configuration:

{
  "mcpServers": {
    "GoogleAds": {
      "command": "pipx",
      "args": [
        "run", "--spec",
        "git+https://github.com/jeffreywlai/google_ads_mcp.git",
        "run-mcp-server"
      ],
      "env": {
        "GOOGLE_ADS_CREDENTIALS": "PATH_TO_YAML"
      },
      "timeout": 30000
    }
  }
}

Option C: Direct Launch

uv run -m ads_mcp.server

Hosted Auth / Transport Options

Use run-mcp-server-http to launch the streamable-HTTP server. The run-mcp-server script is reserved for stdio clients.

The runtime uses FastMCP 3.4.x (3.4.8 or newer) and MCP 1.x (1.30 or newer). These bounds preserve per-client mutation unlocking. FastMCP 4 / MCP 2's modern protocol changes session state; adopting them requires migrating and testing that workflow (see the migration guide). Black and pydantic-core follow Pyink's and Pydantic's exact dependency pins. Cryptography uses the 48.x series on Windows and Intel Macs to preserve platform support removed in 49; other platforms use 50.x or newer.

Authenticated HTTP sessions are bound to the identity that created them. Idle HTTP sessions expire after 30 minutes; an open GET stream keeps a session active. After expiry, the next request returns 404 and the client must initialize a new session. The server accepts at most 10,000 simultaneous sessions and returns 503 for new sessions while that limit is reached. HTTP request bodies are limited to 4 MiB; larger requests return 413 and should be split into smaller batches.

When running the HTTP server with Google OAuth enabled, these optional env vars control the new hardening and resumability behavior:

• FASTMCP_SERVER_AUTH_ALLOWED_CLIENT_REDIRECT_URIS: Comma-separated redirect URI allowlist. Required for non-loopback OAuth base URLs.
• FASTMCP_SERVER_PING_INTERVAL_MS: Ping cadence for long-lived HTTP sessions.
• FASTMCP_STREAMABLE_HTTP_RETRY_INTERVAL_MS: Suggested retry interval for resumable streamable-http reconnects.
• GOOGLE_ADS_MCP_EXPORT_DIR: Directory that explicit export_gaql_csv output paths must stay within. Defaults to the OS temp directory (explicit paths under /tmp are also accepted on POSIX systems).
• GOOGLE_ADS_ADS_ASSISTANT: Override the Google Ads request tag. By default, the server sends a compact google-ads-mcp-<version> tag automatically.

Explicit CSV paths use private staging and directory-relative file operations to prevent symlink redirection during saving. This requires the directory descriptor support available on macOS and Linux; on other platforms, omit output_path to export to an automatically generated temporary file. The filesystem must permit hard links, including to the existing CSV when overwriting it; permission restrictions cause the export to fail safely. On macOS, staging directories with inherited ACL entries are rejected because mode bits alone cannot establish privacy. Use an export directory without inherited ACL entries, or omit output_path for an automatically generated temporary file. Empty staging folders are retained when their parent permits other users to change directory entries; cleanup removes them only in an owner-controlled parent. As with private staging itself, this permission boundary trusts processes running as the same operating-system user. An overwrite briefly moves the existing CSV into private staging before publishing the new file, so its destination may be absent during that step. If another writer occupies the destination, the export fails without replacing that writer's file and retains any CSV it cannot restore in private staging. Unexpected exceptions or interruptions also retain the captured CSV until publication or restoration is confirmed. If a concurrent writer substitutes a folder, recovery restores it with an exclusive rename. An occupied destination or unsupported filesystem keeps that folder and its contents in private staging for recovery.

For either transport, set GOOGLE_ADS_MCP_DIAGNOSTICS=1 to record startup package versions/build fingerprint, tool timing, exception class, and result envelope bytes on stderr. These optional records omit arguments, payloads, credentials, and error messages. Result bytes include MCP text/structured duplication before transport framing; they are not the logical-response limit.

💬 Usage Examples

Once connected, just talk naturally:

Querying

"List all my campaigns and their status"
"Show me the top 10 keywords by conversions this month"
"What's my total spend across all campaigns last week?"
"Show me ad performance broken down by device"

Exporting

"Export all keyword performance data to CSV"
"Export campaign metrics for the last 90 days to a file"

Managing

"Pause campaign 123456789"
"Set the daily budget for campaign 123 to $50"
"Update the CPC bid for ad group 456 to $2.50"
"Enable the ad I just paused"

Keywords

"Generate keyword ideas for 'digital marketing agency'"
"Add 'free' and 'cheap' as negative keywords to my shared set"
"What negative keyword lists are attached to campaign 123?"

Labels

"Create a label called 'Q1 Test'"
"Apply the label to campaigns 111, 222, and 333"
"Remove the 'Old' label from all ad groups"

Optimization

"What's my optimization score?"
"Show me recommendations for campaign 123"
"Apply the top recommendation"
"What bid simulations are available for my campaigns?"

Search Terms

"What search terms are triggering my ads?"
"Analyze search terms and find negative keyword candidates"
"Show me search term insights for campaign 123"

Reporting

"Show me performance by device for the last 30 days"
"What's my impression share across campaigns?"
"List keyword quality scores for campaign 123"
"Summarize quality scores across all my campaigns"
"What are the conversion goals for campaign 123?"
"Show me RSA ad strength for my ad groups"
"What conversion actions do I have set up?"
"Show audience performance at the ad group level"
"Break down performance by geography"

Performance Max

"List asset group assets and their serving status"
"Show me the top asset combinations for my PMax campaign"
"What placements are my PMax ads showing on?"

Change History

"What changed in my account in the last 7 days?"
"Show me change events for campaign 123"

Conversion Uploads

"Upload a click conversion for gclid ABC123 on conversion action 456"
"Upload a call conversion for caller +1234567890"
"Validate my click conversion payload without actually uploading"

Smart Campaigns

"Suggest keyword themes for Joe's Plumbing"
"Generate ad headlines for my bakery website"
"What budget should I set for a smart campaign targeting plumbers in the US?"

🏗️ Project Structure

google_ads_mcp/
├── ads_mcp/
│   ├── server.py              # Server entry point (Gemini / SSE)
│   ├── stdio.py               # Server entry point (Claude Code / stdio)
│   ├── coordinator.py         # Shared FastMCP instance + search/visibility config
│   ├── tooling.py             # Shared tool decorators and annotations
│   ├── utils.py               # Shared utility constants
│   ├── scripts/
│   │   └── generate_views.py  # Auto-update reporting view YAMLs
│   ├── tools/
│   │   ├── api.py             # Core: execute_gaql, list_accessible_accounts
│   │   ├── docs.py            # GAQL & reporting docs, tool guide, visibility controls
│   │   ├── audiences.py       # AudienceService audience creation
│   │   ├── campaigns.py       # Campaign status, budget, targeting, audiences
│   │   ├── ad_groups.py       # Pause, enable criteria, update bid
│   │   ├── ads.py             # Pause, enable ads
│   │   ├── keywords.py        # Pause, enable, update bid
│   │   ├── negatives.py       # Shared sets & campaign negatives
│   │   ├── labels.py          # Label CRUD & assignment
│   │   ├── keyword_planner.py # Keyword research
│   │   ├── smart_campaigns.py # Smart campaign suggestions
│   │   ├── planning.py        # Benchmarks, reach and creator insights
│   │   ├── resources.py       # Strict native resource mutations
│   │   ├── assets.py          # PMax options and attestations
│   │   ├── goals.py           # Unified lifecycle goal mutations
│   │   ├── recommendations.py # Optimization score & recommendations
│   │   ├── search_terms.py    # Search term insights & analysis
│   │   ├── simulations.py     # Bid & budget simulations
│   │   ├── changes.py         # Change history auditing
│   │   ├── conversions.py     # Offline conversion uploads (click & call)
│   │   ├── reporting.py       # Curated reporting tools (device, geo, impression share, etc.)
│   │   ├── performance_max.py # PMax asset & placement diagnostics
│   │   ├── _gaql.py           # Shared GAQL query helpers
│   │   └── _campaign_context.py # Cached campaign status/spend context
│   └── context/               # GAQL docs, reporting view YAMLs, tool guide
├── tests/                     # Mirrors source structure
├── pyproject.toml
└── README.md

🛠️ Development

uv sync                          # Install dependencies
uv run pytest                    # Run tests
uv run pyink .                   # Format (Google style)
uv run pylint ads_mcp tests      # Lint

Adding a Tool

1. Create or edit a file in ads_mcp/tools/
2. Import from ads_mcp.coordinator import mcp_server as mcp
3. Decorate with @mcp.tool()
4. Register in ads_mcp/server.py
5. Add tests in tests/tools/

See CONTRIBUTING.md for full details.

⚠️ Disclaimer

Copyright Google LLC. Supported by Google LLC and/or its affiliate(s). This solution, including any related sample code or data, is made available on an "as is," "as available," and "with all faults" basis, solely for illustrative purposes, and without warranty or representation of any kind. This solution is experimental, unsupported and provided solely for your convenience. Your use of it is subject to your agreements with Google, as applicable, and may constitute a beta feature as defined under those agreements. To the extent that you make any data available to Google in connection with your use of the solution, you represent and warrant that you have all necessary and appropriate rights, consents and permissions to permit Google to use and process that data. By using any portion of this solution, you acknowledge, assume and accept all risks, known and unknown, associated with its usage and any processing of data by Google, including with respect to your deployment of any portion of this solution in your systems, or usage in connection with your business, if at all. With respect to the entrustment of personal information to Google, you will verify that the established system is sufficient by checking Google's privacy policy and other public information, and you agree that no further information will be provided by Google.

📄 License

Licensed under the Apache License 2.0.

📬 Contact

Questions, suggestions, or feedback? Open an issue.

---

Built with FastMCP and Google Ads API v25.2