Google Ads MCP Server

To find opportunities lost due to ad rank, bids, or budgets, analyze impression share metrics using the search tool:

1. Query Impression Share:
   • Resource: campaign.
   • Fields: campaign.name, metrics.search_impression_share, metrics.search_rank_lost_impression_share, and metrics.search_budget_lost_impression_share.
2. Analyze Results:
   • Budget Issues: High search_budget_lost_impression_share suggests the budget is too low.
   • Rank Issues: High search_rank_lost_impression_share suggests issues with bids or ad quality.

You can use gcloud to set up Application Default Credentials. Ensure the credentials include the Google Ads API scope: https://www.googleapis.com/auth/adwords.

Set up ADC with user credentials:

gcloud auth application-default login \
  --scopes https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform \
  --client-id-file=YOUR_CLIENT_JSON_FILE

Set up ADC with service account impersonation:

gcloud auth application-default login \
  --impersonate-service-account=SERVICE_ACCOUNT_EMAIL \
  --scopes=https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform

After running the command, note the PATH_TO_CREDENTIALS_JSON provided in the output for use in your MCP client configuration.

This repository provides specialized workflows called Agent Skills. The available skill is:

• account-performance-diagnostics: Located in ads_mcp/skills/account-performance-diagnostics. It diagnoses issues like conversion loss, low lead flow, and lost opportunities.

To use these skills, point your skills-compatible AI agent (such as Claude Code, Cursor, or Antigravity CLI) to the skill directory. For Antigravity CLI, you can copy the folder to your skills directory or reference it.

To set up the server, follow these high-level steps:

1. Configure Python: Install pipx.
2. Configure Developer Token: Obtain a Google Ads Developer Token with at least Explorer access.
3. Enable APIs: Enable the Google Ads API in your Google Cloud project.
4. Configure Credentials: Choose one of three methods:
   • FastMCP OAuth Proxy: For web service deployments using dynamic user authentication.
   • Application Default Credentials (ADC): Using gcloud to authenticate locally or via service account impersonation.
   • Google Ads API Python Client Library: Reusing an existing google-ads.yaml configuration.
5. Configure MCP Client: Add the server to your client (e.g., Claude Code, Cursor, VS Code) using the appropriate configuration format.

When conversions or conversion value decline, follow these steps using the Google Ads MCP server:

1. Discover Fields: Use get_resource_metadata with the campaign or ad_group resource to verify correct field names.
2. Query Performance: Use the search tool to retrieve data.
   • Resource: campaign or ad_group.
   • Fields: Use campaign.name, metrics.conversions, metrics.conversion_value, and metrics.cost_micros.
   • Segments: Include segments.date, segments.device, or segments.conversion_action to isolate the cause.
   • Conditions: Use date filters (e.g., segments.date >= 'YYYY-MM-DD') to compare periods.
3. Analyze: Determine if the loss is isolated to specific devices or conversion actions.
4. Check Uploads: If using offline conversions, inspect offline_conversion_upload_conversion_action_summary for upload errors.

If lead flow has dropped, follow this systematic diagnostic approach:

1. Confirm the Drop: Query conversions segmented by segments.date for the recent period versus the previous period.
2. Isolate the Cause:
   • Traffic Drop: If clicks or impressions decreased, check Impression Share metrics (Budget vs. Rank) or general search volume trends.
   • Conversion Rate Drop: If the ratio of conversions to clicks decreased, check breakdowns by segments.device or segments.conversion_action.
3. Check Account Changes: Query the change_event resource to identify recent modifications to bids, budgets, or targeting that coincide with the performance drop.

Important Constraint: Queries to the change_event resource must include a LIMIT of 10,000 or less.

When deploying to Google Cloud Run, the following environment variables must be configured:

You can selectively enable/disable tools or entire categories (namespaces) and customize their prefixes using a tools_config.yaml file.

Resolution order for configuration:

1. Path specified by GOOGLE_ADS_MCP_TOOLS_CONFIG environment variable.
2. tools_config.yaml in the current working directory.
3. Default tools_config.yaml bundled with the package.

If an explicitly requested file is missing or invalid, the server will fail to start.

namespaces:
  # Enable category 'customers' with default prefix -> "customers_list_accessible_customers"
  customers: true

  # Enable category 'search' with a custom prefix -> "query_search"
  search: "query"

  # Fine-grained control over tools in a category
  metadata:
    enabled: true
    prefix: "metadata"
    enabled_tools:
      - get_resource_metadata: true