Google Ads guide

Google Ads MCP Server

The Google Ads MCP server is a bridge between an MCP-compatible AI client and the Google Ads API. It lets an AI application discover approved tools, query Google Ads account data, and return campaign information in a form that can be used in a natural-language workflow. The official Google Ads repository is currently focused on reporting and diagnostics: its documented tools include search, resource metadata, and listing customers accessible to the authenticated user, while its resources describe metrics, segments, the API discovery document, and release notes.

The server does not remove the need for Google Ads API credentials, developer token access, customer-account permissions, or careful data handling. It also does not make every MCP server safe or read-only. Verify the exact repository, commit, enabled tool configuration, transport, and permissions before connecting an AI client to an advertising account.

This guide explains what the official Google Ads MCP server does, how its architecture and authentication fit together, how to configure it responsibly, and what to check before considering any write-capable extension.

1. What the Google Ads MCP server is

MCP, or Model Context Protocol, is a standard way for an AI host to discover and call tools exposed by a server. The host may be an AI desktop app, coding assistant, or agent runtime. The MCP client manages the connection; the server translates an approved tool call into an operation against a service such as the Google Ads API. The model chooses a tool only within the interface the server exposes and the permissions the authenticated identity has.

Google announced its open-source Google Ads API MCP server as a way for MCP-compatible AI applications to understand and analyze advertising campaigns using natural language. Google described the initial release as read-only for reporting and diagnostics. The current official repository remains the source to check for the tools, resources, configuration, authentication flow, and current implementation.

The official server’s documented scope

At the time this article was last updated, the repository documents these core tools:

  • Search: retrieve information from a Google Ads account using the server’s supported query path;
  • Resource metadata: inspect the structure and available fields for a Google Ads API resource such as a campaign;
  • Accessible customers: list customer IDs directly accessible to the authenticating user.

It also documents resources for the API discovery document, available metrics, segments, and API release notes. That combination is useful for campaign reporting, diagnostics, schema discovery, and asking an agent to explain account data without granting it a budget-edit or campaign-mutation tool.

MCP is not the Google Ads API itself

The Google Ads API remains the system of record and enforces its own authentication, customer access, developer-token access level, quotas, and permissible-use rules. MCP is the connection layer that makes selected API capabilities available to an AI client. If the API identity cannot access a customer, the MCP client cannot manufacture that access. If the server exposes a tool that can mutate data, the API and account permissions still determine what the request can do.

The protocol also does not guarantee that a server is official, secure, current, or correctly configured. A third-party server may add write tools, collect extra data, use a different authentication flow, or lag behind the current API. Treat the server repository, version, configuration, and deployment as part of the security boundary.

2. How the Google Ads MCP connection works

The useful mental model is a chain, not a direct connection from a chat box to a campaign:

AI host → MCP client → Google Ads MCP server → Google Ads API → customer account

The model proposes a tool call from the tool schema. The MCP client sends that call to the server, the server authenticates to Google and translates the request, and the API returns data or an error. The server returns the result to the client, which presents it to the model and user. Every link can restrict, log, reject, or misinterpret the request.

Tools and resources have different roles

An MCP tool is an action the model can invoke, such as searching account data or listing accessible customers. A resource is contextual information the client or model can read, such as a discovery document, metric definition, segment description, or release note. The distinction matters when reviewing risk: a search tool may expose sensitive performance data, while a mutation tool could change a live campaign.

The official server’s tools_config.yaml allows an operator to enable or disable tool categories and individual tools and to set namespace prefixes. Read the resolved configuration rather than assuming the default. A tool list shown by a client is not proof that the tool is safe, read-only, or appropriate for the current customer.

Customer and manager IDs define the account scope

Most prompts need a customer ID so the server knows which account to query. The official setup notes that customer IDs are ten-digit values and should be used without the hyphens shown in some Google Ads interfaces. If access is through a manager account, the login customer ID identifies the manager context while the target customer ID identifies the account being queried.

Make the account scope explicit in a team workflow. “Show my campaign data” is ambiguous when an identity can access several customers. Prefer a prompt or tool wrapper that states the customer ID, account name, date range, currency, and whether a manager or child account is intended. Never let a model infer the target account from a stale conversation when an explicit identifier is available.

Read-only still exposes valuable data

The official repository warns that the MCP server exposes your data to the agent or LLM you connect to it. Read-only access protects against direct mutations but does not prevent the model, host, logs, or a compromised server from seeing campaign names, spend, conversion performance, customer identifiers, search terms, audiences, or other account information. Decide which people, models, transports, and logs are allowed to receive that data before installing the server.

3. Set up the official Google Ads MCP server

Treat setup as an API integration with an MCP adapter, not as a browser extension. The exact repository instructions should be checked at the time of installation, but the current official flow has five parts: Python tooling, a developer token, an enabled Google Ads API project, credentials with customer access, and an MCP client configuration.

Confirm prerequisites and API access

Before installing, confirm that you have:

  • a Google Cloud project where the Google Ads API is enabled;
  • a Google Ads manager account or another supported path to a developer token;
  • a developer token with access to the accounts you intend to query;
  • a Google Ads customer account and a user or service identity authorized for it;
  • an MCP-compatible host that can run a local process or connect to an HTTP endpoint;
  • a plan for secret storage, logging, and which data the AI host may receive.

Google’s API access-level documentation shows that developer-token access controls which accounts and API operations are available. The official MCP repository currently notes that querying production accounts requires at least Explorer access. A token limited to test accounts will not work for production reporting, regardless of how the MCP client is configured.

Choose credentials deliberately

The official repository documents several credential paths:

  • a FastMCP OAuth proxy for a web-accessible server, using a Google Cloud OAuth client and a base URL;
  • Google Application Default Credentials for a local or service environment;
  • an existing Google Ads API Python client configuration.

Use an interactive user flow when a person should authorize access and a service identity or controlled impersonation flow when a managed service needs to run unattended. In either case, grant only the customer accounts and access needed for the reporting task. Keep OAuth client secrets, service-account keys, developer tokens, and credential files outside source control and outside model prompts.

The Google Ads API first-call guide explains the developer token, manager account, customer ID, OAuth 2.0, Google Cloud project, and customer-account access involved in a normal API setup.

Run locally or expose a protected HTTP endpoint

For a local developer workflow, the repository shows an MCP client configuration that starts the server as a separate process. This keeps the server on the developer machine and uses the host’s standard MCP configuration. Pin the repository revision or package version you reviewed, and inspect the enabled tools before connecting a production customer.

For a shared or remote workflow, the current repository documents a streamable-http transport through an OAuth proxy and an /mcp endpoint. A remote endpoint needs more controls: HTTPS, OAuth client validation, redirect-URI protection, token storage, network policy, rate limits, structured logs, and tenant or customer-account isolation. “The endpoint has a login page” is not a complete security review.

Do not deploy the server with an unauthenticated public endpoint. The repository includes deployment examples, but those examples still require a real identity, secret management, and an access policy designed for the organization using the server.

Verify the connection before querying real data

Use a low-risk test account or the smallest approved customer scope first. Check that the client can list the expected accessible customers, that the target customer ID is correct, that the metric and segment resources match the API version, and that a simple search returns the expected date range. Confirm that no write-capable tool is present if the intended workflow is read-only.

Record the server repository or version, tool configuration, credential type, customer scope, client name, and approval owner. This record makes a later change to the MCP server auditable instead of looking like a mysterious change in the AI assistant’s behavior.

4. Use the MCP server for reporting and diagnostics

The official read-only scope is a good fit for questions that require account context but should not directly change a campaign. Give the model a narrow customer ID, a complete date range, a conversion definition, and the business question. Ask it to show the fields and assumptions it used.

Start with explicit, repeatable queries

Useful first prompts include:

  • “List the customers available to this credential. Do not query campaign data until I select one customer ID.”
  • “For customer 1234567890, compare Search campaign cost, clicks, conversions, conversion value, and average CPC for the last two complete calendar weeks. State the currency, date range, and conversion definition.”
  • “Use the resource metadata and metric resources to verify whether these fields and segments are valid before running the report.”
  • “Find campaigns with cost in the selected period and zero recorded primary conversions. State that this is a reported-conversion result, not proof that no business conversions occurred.”

The prompts are intentionally specific. They prevent the model from silently switching accounts, mixing incomplete periods, or treating a metric label as a business definition. Save a successful query and its assumptions so a later report can be compared with the same logic.

Separate retrieval from interpretation

Ask the server or API layer for the raw fields and the model for explanation. That separation makes it easier to check whether a conclusion follows from the data. For example, “conversions fell” is an observation; “the landing page caused the fall” is a hypothesis that needs analytics, tracking, and business evidence.

Keep attribution windows, conversion lag, time zone, currency, primary-versus secondary conversion choice, and segmentation visible in the report. If the agent cannot see one of these inputs, mark the conclusion as incomplete rather than filling the gap with a generic Google Ads recommendation.

Handle API limits and changing schemas

MCP does not bypass Google Ads API quotas. Google documents rate limits by queries per second for the client customer ID and developer token and describes throttling, batching, limited concurrency, and queueing as ways to reduce rate limit errors. See the Google Ads API rate-limit guidance before running a large manager-account report.

Use the server’s metadata and discovery resources before relying on a field, segment, or API version. When the API changes, a report that used to work may fail, return a different field, or produce a different interpretation. Keep the API version, server revision, query, request time, and error message with the report.

Treat account content as data, not instructions

Campaign names, ad text, search terms, URLs, and other returned fields may contain text that looks like an instruction to the model. The server should treat those values as account data. Do not let text retrieved from an ad or landing page override the task scope, reveal credentials, change the destination customer, or authorize a tool that the operator did not approve.

Keep the MCP client, server, model, and tool configuration under the team’s control. Review what is sent to external model providers, whether prompts or tool results are retained, and whether logs include customer or search-query data. The official repository’s warning about exposing data to the connected agent is a reason to perform that review before production use.

5. Secure an MCP server before connecting a Google Ads account

The advertising account, API credentials, MCP server, client, and model are one combined control surface. A secure Google Ads MCP deployment protects each boundary instead of assuming that the protocol itself makes an AI action safe.

Protect local and remote transports differently

For a local stdio process, restrict which users and processes can start the server, protect environment variables and credential files, and inspect the client configuration before allowing automatic tool calls. Do not copy a production credential into a shared developer machine simply because the local setup is convenient.

For a remote HTTP deployment, use HTTPS and an OAuth flow appropriate to the MCP client and server. The MCP authorization specification defines authorization for protected HTTP-based servers and includes requirements around token handling, resource audience, discovery, and secure redirect URIs. Use short-lived tokens where practical, validate the intended audience, protect refresh tokens, and never place bearer tokens in a URL query string.

Scope identities and tools

Create a separate integration identity for the MCP service where possible. Limit which Google Ads customers it can access, which model hosts can connect, and which tools are enabled. Keep search and metadata tools available for a read-only reporting workflow; do not enable a write category just because the client can display it.

Review access after a staff change, customer transfer, server redeployment, or credential rotation. A manager-account credential can have a much wider scope than a person expects. The login customer ID, target customer ID, OAuth client, server configuration, and model workspace should all be documented together.

Log without leaking secrets

Log connection events, authenticated identity, customer scope, tool name, request ID, duration, error, and result status. Redact access tokens, developer tokens, service-account keys, payment details, customer lists, and unnecessary search-query or audience data. Limit access to logs and set retention according to the organization’s privacy and contractual requirements.

The official repository notes that an extra header is added to Google Ads API calls to collect usage data and improve the product. Review that behavior and your organization’s disclosure or data-governance requirements before using the server with sensitive accounts.

Treat third-party write tools as a separate product

If a different MCP server exposes budget, bid, campaign, ad, keyword, audience, or conversion mutations, do not assume that the official read-only guarantees apply. Review the source, release history, dependencies, authentication, telemetry, tool schemas, and Google Ads API permissible use. Pin a reviewed version rather than pulling an unreviewed branch at every startup.

Require a human approval step for every high-impact operation, and add server- side checks for customer scope, maximum budget delta, affected-entity count, allowed campaign types, and required fields. Use a test account, preview or dry-run mode, Google Ads Change history, and a rollback procedure. Keep a read-only reporting server separate from a write-capable automation service so an investigative prompt cannot accidentally acquire mutation authority.

Monitor the integration itself

An account can be healthy while the MCP path is stale or failing. Monitor authentication failures, API errors, rate-limit responses, schema changes, unexpected customer IDs, tool-list changes, latency, and unusual query volume. Alert on a tool configuration change or credential use from an unexpected host. Run a small known-good report after a deployment and compare it with the prior result before declaring the integration healthy.

6. Google Ads MCP server checklist

Before connecting an MCP client to an account, verify:

  • The server comes from the official Google Ads organization or a reviewed third-party source, and the exact revision is recorded.
  • The documented tool list matches the intended read-only or write-capable workflow.
  • The resolved tools_config.yaml enables only the tools and namespaces that have been approved.
  • The Google Ads API project, developer token, OAuth flow, and customer-account access are valid for the target environment.
  • The target customer ID and manager login customer ID are explicit and tested.
  • Credentials are stored outside source control, prompts, and ordinary logs.
  • The AI host, MCP client, server transport, and model provider are allowed to receive the account data being queried.
  • Production reporting was tested with a small scope and a known-good result.
  • Rate limits, API version changes, tool configuration changes, and authentication failures are monitored.
  • Any write-capable operation has human approval, validation, Change history, limits, and a rollback path.

For the wider agent design around this integration, read the Google Ads AI agent guide, the Google Ads automation tools guide, and the Google Ads alerts workflow.

7. Final takeaway

The official Google Ads MCP server is useful because it gives compatible AI clients a structured, natural-language path to Google Ads reporting and diagnostics. As of this guide’s last update, its documented core is read-only, but the repository and tool configuration are the source of truth for what a particular revision exposes. Treat that scope as a capability to verify, not a permanent promise.

MCP makes an integration easier to use; it does not make authorization, customer scoping, privacy, API quotas, or AI interpretation disappear. Start with a pinned read-only server, a small customer scope, explicit queries, and auditable logs. Add write capabilities only as a separate, reviewed system with strong approval and rollback controls.

If you want to organize this operating model into an internal brief, review the current scope of adz.so and use only the workflows and capabilities available in the product today.