Google Ads MCP server: Developer integration guide

The Model Context Protocol (MCP) is an open standard that enables Large Language Models (LLMs) to securely interact with external data and applications. The Google Ads MCP server provides a standardized bridge to the Google Ads API, which lets AI agents analyze and retrieve campaign data using natural language.

Community resources and support

• GitHub repository: Find demos, examples, and report bugs or suggest features in the google-ads-mcp repository.

  Use the Issues tab for bug reports and feature requests.

• Community: Join the #ads-api-ai-tools channel on the Google Advertising Community Discord.

Technical overview

By implementing this MCP server, you eliminate the need to write custom "glue code" for Google Ads API authentication, resource fetching, and data parsing. The server exposes specific tools that an LLM can discover and invoke autonomously.

Key specifications

• Protocol: MCP (Model Context Protocol)
• Mode: Read-only (current release)
• Language: Python
• Transport: Standard input/output (stdio) or Streamable HTTP (streamable-http / Cloud Run)
• Authentication: OAuth 2.0 or service account

How the interaction loop works

1. Request: A user submits a query such as "How is my campaign performance this week?".
2. Discovery: The LLM inspects its available tools and identifies the google-ads-mcp search capabilities.
3. Execution: The MCP server executes the underlying Python logic to query the Google Ads API.
4. Context injection: Structured results are returned to the LLM's context window.
5. Response: The LLM synthesizes the data into a human-readable answer.

Get started

Follow these steps to configure and use the Google Ads MCP server.

Prerequisites

Before configuration, ensure you have the following credentials from the Google Cloud console:

• Project ID: Your Google Cloud project ID (GOOGLE_PROJECT_ID). Check the Google Ads API overview page to ensure that your project has Explorer access, Basic access, or Standard access levels. If not, apply for one of these access levels. Note that developer tokens (GOOGLE_ADS_DEVELOPER_TOKEN) were sunset on September 9, 2026, and are no longer required in the latest version of the Google Ads MCP server because API access levels are associated with the Google Cloud project.
• OAuth credentials: Either an OAuth 2.0 Client ID/Client secret pair, or a set of application default credentials.

Configuration

To integrate the server into an MCP-compatible host, add the following entry to your host's MCP configuration file, such as settings.json, and point GOOGLE_APPLICATION_CREDENTIALS to your ADC JSON file (or configure default ADC with gcloud auth application-default login). If you access accounts through a manager account, you can also set GOOGLE_ADS_LOGIN_CUSTOMER_ID. Consult your host's documentation for the exact location and filename of this configuration.

{
  "mcpServers": {
    "google-ads-mcp": {
      "command": "pipx",
      "args": [
        "run",
        "--spec",
        "git+https://github.com/googleads/google-ads-mcp.git",
        "google-ads-mcp"
      ],
      "env": {
        "GOOGLE_PROJECT_ID": "YOUR_PROJECT_ID",
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/credentials.json"
      }
    }
  }
}

Deployment on Google Cloud

Instead of hosting this MCP server locally, you can host it on Google Cloud Run or on any other cloud-based infrastructure. This is useful if you want to share the server across different agents or run it as a web service.

Prerequisites

1. A Google Cloud project.

2. The gcloud command-line tool installed, authenticated, and with an active project configured:

   gcloud config set project YOUR_PROJECT_ID
   

Build and push a Docker image

You can use Cloud Build to build and push the image to the Artifact Registry without needing Docker installed locally.

1. Create a repository in Artifact Registry:

   gcloud artifacts repositories create mcp-servers \
     --repository-format=docker --location=us-central1
   

2. Go to the project directory:

   cd <full path>/google-ads-mcp
   

3. Build and submit the image:

   gcloud builds submit \
     --tag us-central1-docker.pkg.dev/YOUR_PROJECT_ID/mcp-servers/google-ads-mcp:latest .
   

   Note that this step must be performed whenever you want to update the deployed server to the latest version.

Deploy to Google Cloud Run

Make sure to set the required environment variables:

• GOOGLE_PROJECT_ID: Your Google Cloud project ID, which has the appropriate API access levels.
• GOOGLE_ADS_MCP_OAUTH_CLIENT_ID: The OAuth 2.0 Client ID (configured as a Web application in your Google Cloud project) for application-level OAuth authentication. Ensure that:
  • You have added the appropriate authorized redirect URIs for any AI clients you plan to connect (such as https://claude.ai/api/mcp/auth_callback, https://chatgpt.com/connector_platform_oauth_redirect, or https://antigravity.google/oauth-callback).
  • You have added the https://www.googleapis.com/auth/adwords scope to the OAuth consent screen under APIs & Services > OAuth consent screen > Data Access (Add or remove scopes).
  • If your OAuth consent screen publishing status is set to Testing (the default), you have added the Google Accounts connecting to the MCP server as Test users under APIs & Services > OAuth consent screen > Audience (Test users > + Add users).
• GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET: The OAuth Client secret corresponding to the OAuth Client ID.
• GOOGLE_ADS_MCP_BASE_URL: The public base URL where your MCP server is accessible (for example, https://google-ads-mcp-xyz-uc.a.run.app). Because Google Cloud Run generates this URL during initial deployment, deploy without this variable first, then update the service after deployment.
• FASTMCP_HOST: Set this to 0.0.0.0 to allow FastMCP to accept connections from all IP addresses.

Deploy the service to Google Cloud Run:

gcloud run deploy google-ads-mcp \
  --image us-central1-docker.pkg.dev/YOUR_PROJECT_ID/mcp-servers/google-ads-mcp:latest \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars="GOOGLE_PROJECT_ID=YOUR_PROJECT_ID,GOOGLE_ADS_MCP_OAUTH_CLIENT_ID=YOUR_CLIENT_ID,GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET=YOUR_CLIENT_SECRET,FASTMCP_HOST=0.0.0.0"

After Cloud Run completes the deployment, retrieve the assigned service URL and update the service with the GOOGLE_ADS_MCP_BASE_URL environment variable:

gcloud run services update google-ads-mcp \
  --region us-central1 \
  --update-env-vars="GOOGLE_ADS_MCP_BASE_URL=https://your-cloud-run-url.a.run.app"

Authentication and security model

Deploying with --allow-unauthenticated disables Cloud Run's infrastructure-level IAM check (roles/run.invoker) so that external AI clients can connect without needing Google Cloud service account tokens. Authentication is instead delegated to the application layer:

• When GOOGLE_ADS_MCP_OAUTH_CLIENT_ID and GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET are provided, the MCP server enforces Google OAuth 2.0 on all incoming requests, challenging unauthenticated callers with an HTTP 401 response. All tool requests execute strictly under the authenticated caller's OAuth identity.
• Omitting --allow-unauthenticated enforces Cloud Run infrastructure IAM, which requires callers to pass Google Cloud OIDC identity tokens with each request. Because standard AI clients (such as Claude and ChatGPT) authenticate using end-user OAuth rather than Google Cloud IAM identity tokens, direct connections from these platforms require --allow-unauthenticated with application-level OAuth.

Caution: Never omit GOOGLE_ADS_MCP_OAUTH_CLIENT_ID and GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET when deploying with --allow-unauthenticated. These environment variables trigger the server to switch from local stdio mode to streamable-http transport. Without them, the server cannot enforce authentication and falls back to Application Default Credentials (ADC), exposing the container's service account credentials to unauthenticated callers.

Configure the MCP client

After deployment, configure your MCP client with the Cloud Run URL. Because the server requires OAuth 2.0 authentication, the client must support the MCP OAuth flow or supply an authorized Bearer token:

• OAuth-enabled clients: For clients that support MCP OAuth discovery (such as Antigravity), connecting to the endpoint triggers an authentication prompt to sign in with Google and grant the https://www.googleapis.com/auth/adwords scope (listed as .../auth/adwords in the Google Cloud console).
• Third-party AI platforms (Claude, ChatGPT): In your client's connector or integration settings, add a custom connector pointing to your Cloud Run URL with the /mcp path (for example, https://your-cloud-run-url.a.run.app/mcp), select OAuth 2.0 authentication (using your own OAuth Client ID and Client secret), and ensure the client's callback URI is added to your OAuth client's authorized redirect URIs. (Allowlisted participants of the hosted endpoint pilot can also refer to the hosted MCP setup guide.)
• Clients without OAuth support: Clients that do not support HTTP OAuth flows will receive an HTTP 401 Unauthorized response. For these tools, use the local stdio configuration instead.

Example configuration for an OAuth-capable client (for example, ~/.gemini/settings.json):

{
  "mcpServers": {
    "google-ads-mcp": {
      "httpUrl": "https://your-cloud-run-url.a.run.app/mcp"
    }
  }
}

Core capabilities (tools)

The server exposes tools designed for account discovery and performance reporting:

• list_accessible_customers: Returns the list of Google Ads customer IDs and account names accessible to the authenticated user.
• search: Executes Google Ads Query Language (GAQL) requests to fetch resource metrics, budgets, and status.

• get_resource_metadata: Retrieves metadata about a Google Ads API resource type, for example "campaign".

  This is useful to understand the structure of the data and what fields are available for querying.

Note: This implementation is strictly read-only. It cannot modify bids, pause campaigns, or create new assets.

Sample prompts to start

Ask what the server can do:

What can the google-ads-mcp server do?

Ask about customers:

What customers do I have access to?

Ask about campaigns:

How many active campaigns do I have?
How is my campaign performance this week?
Give me a report of the top spending campaigns split by device category over the
last 7 days for account 1234567890