---
title: "Google Ads MCP Setup: Complete Beginner Quickstart"
slug: "google-ads-mcp-setup-guide"
published: "2026-05-10"
updated: "2026-05-11"
categories:
  - "Tools"
tags:
  - "Google Ads MCP setup"
  - "google-ads-mcp"
  - "Google Ads API"
  - "gcloud auth application-default login"
  - "OAuth client ID"
  - "Application Default Credentials"
  - "google ads developer token"
  - "GOOGLE_ADS_LOGIN_CUSTOMER_ID"
  - "Codex MCP"
  - "Gemini MCP"
  - "Claude MCP"
  - "pipx google-ads-mcp"
llm-intent: "how-to"
audience-level: "beginner"
llm-purpose: "Google Ads MCP setup: step-by-step beginner guide to install google-ads-mcp, configure OAuth/ADC, enable the Google Ads API, and connect Codex, Gemini…"
llm-prereqs:
  - "gcloud"
  - "Google Cloud Console"
  - "Python 3"
  - "pipx"
  - "google-ads-mcp"
  - "Codex"
  - "Gemini"
  - "Claude"
---

**Summary Triples**
- (Google Ads MCP Setup: Complete Beginner Quickstart, expresses-intent, how-to)
- (Google Ads MCP Setup: Complete Beginner Quickstart, covers-topic, Google Ads MCP setup)
- (Google Ads MCP Setup: Complete Beginner Quickstart, provides-guidance-for, Google Ads MCP setup: step-by-step beginner guide to install google-ads-mcp, configure OAuth/ADC, enable the Google Ads API, and connect Codex, Gemini…)

### {GOAL}
Google Ads MCP setup: step-by-step beginner guide to install google-ads-mcp, configure OAuth/ADC, enable the Google Ads API, and connect Codex, Gemini…

### {PREREQS}
- gcloud
- Google Cloud Console
- Python 3
- pipx
- google-ads-mcp
- Codex
- Gemini
- Claude

### {STEPS}
1. Create a Google Cloud project
2. Enable the Google Ads API
3. Create an OAuth Client ID JSON
4. Install gcloud, Python, and pipx
5. Obtain a Google Ads developer token
6. Authenticate ADC with adwords scope
7. Verify the ADC scope includes adwords
8. Add google-ads-mcp to your client
9. Restart your MCP client
10. Test queries and troubleshoot

<!-- llm:goal="Google Ads MCP setup: step-by-step beginner guide to install google-ads-mcp, configure OAuth/ADC, enable the Google Ads API, and connect Codex, Gemini…" -->
<!-- llm:prereq="gcloud" -->
<!-- llm:prereq="Google Cloud Console" -->
<!-- llm:prereq="Python 3" -->
<!-- llm:prereq="pipx" -->
<!-- llm:prereq="google-ads-mcp" -->
<!-- llm:prereq="Codex" -->
<!-- llm:prereq="Gemini" -->
<!-- llm:prereq="Claude" -->

# Google Ads MCP Setup: Complete Beginner Quickstart
> Google Ads MCP setup: step-by-step beginner guide to install google-ads-mcp, configure OAuth/ADC, enable the Google Ads API, and connect Codex, Gemini…
Matija Žiberna · 2026-05-10

This guide shows how to set up the official Google Ads MCP server on your own device and connect it to **Codex**, **Gemini**, and **Claude**.

It is written for beginners. It assumes you may have never used MCP, Google Cloud, OAuth credentials, or the Google Ads API before.

The current Google Ads MCP server is designed for reading and analyzing Google Ads data. This setup is not for creating or editing campaigns.

By the end of this guide, you will be able to ask an MCP-compatible client questions like:

- `What customers do I have access to?`
- `How many active campaigns do I have for customer id 1234567890?`
- `List my active campaigns and their clicks, impressions, and cost today.`

Official sources used in this guide:

- Google Ads MCP server: https://github.com/googleads/google-ads-mcp
- Google Ads API auth: https://developers.google.com/google-ads/api/rest/auth
- Google Ads access model: https://developers.google.com/google-ads/api/docs/oauth/access-model
- Google Ads API access levels: https://developers.google.com/google-ads/api/docs/api-policy/access-levels
- Google Cloud ADC docs: https://cloud.google.com/docs/authentication/application-default-credentials
- `gcloud auth application-default login`: https://cloud.google.com/sdk/gcloud/reference/auth/application-default/login

## Requirements

Before you start, make sure you have all of the following.

### 1. Google Cloud account

You need a Google Cloud account.

If you do not already have one, create one here:

https://cloud.google.com/

You need this because the Google Ads MCP setup depends on Google Cloud for:

- creating an API project
- creating OAuth credentials
- authenticating your local machine

### 2. Google Cloud project

You need a Google Cloud project.

This project is used for:

- enabling the Google Ads API
- creating your OAuth Client ID
- associating your local authentication with a specific Google Cloud project

Important:

- the **project name** is just a label
- the **project ID** is the value you will actually use later in config

### 3. OAuth Client ID

You need an **OAuth Client ID JSON** created inside your Google Cloud project.

For a local setup, the simplest choice is:

- credential type: `OAuth client ID`
- application type: `Desktop app`

This is important:

- you need an **OAuth client JSON** for the `gcloud auth application-default login --client-id-file=...` step
- a **service account key** is not the same thing
- do not use a service account JSON file as the `--client-id-file`

### 4. Google Cloud CLI installed on your device

You need the Google Cloud CLI, also called `gcloud`, installed locally.

Install it here:

https://cloud.google.com/sdk/docs/install

After installation, verify it works:

```bash
gcloud --version
```

You will use `gcloud` to:

- enable the Google Ads API
- authenticate your local machine
- verify your access token scopes

### 5. Python 3 and pipx

The Google Ads MCP server is typically launched through `pipx`, so you need:

- Python 3
- `pipx`

Verify both:

```bash
python3 --version
pipx --version
```

### 6. Google Ads access

You also need access on the Google Ads side.

That means:

- a Google Ads account you want to query
- a Google user account that has access to that Google Ads account
- a Google Ads developer token
- optionally, a Google Ads manager account ID if your access goes through an MCC

### 7. Google Ads developer token

The Google Ads API requires a developer token for every request.

You get this from the **API Center** inside Google Ads:

https://ads.google.com/aw/apicenter

Important:

- if your developer token only has test-account access, it will not work on live production accounts
- for live accounts, you need a token with production access such as `Explorer`, `Basic`, or `Standard`, depending on your use case

Google documents access levels here:

https://developers.google.com/google-ads/api/docs/api-policy/access-levels

### 8. An MCP-compatible client

This guide includes setup examples for:

- Codex
- Gemini CLI / Gemini Code Assist
- Claude Code

## What You Are Setting Up

Before the steps, it helps to understand what each piece does.

### What is MCP?

MCP stands for **Model Context Protocol**.

In practical terms, it is a way for AI tools like Codex, Gemini, or Claude to connect to external tools and data sources.

In this case, the external tool is the **Google Ads MCP server**, which lets the AI client query the Google Ads API.

### What is the Google Ads MCP server?

The Google Ads MCP server is a small local process that exposes Google Ads data to an MCP-compatible client.

According to the official repository, it provides tools such as:

- `search`
- `get_resource_metadata`
- `list_accessible_customers`

It also exposes resources like:

- discovery document
- metrics
- segments
- release notes

### What each credential means

Several IDs and credentials are involved. This is where many beginners get confused.

#### Google Cloud project ID

This identifies the Google Cloud project you created.

You will use it as:

```text
GOOGLE_PROJECT_ID
```

#### OAuth client JSON

This is the file you download from Google Cloud after creating an OAuth Client ID.

You use this file with:

```bash
gcloud auth application-default login --client-id-file=...
```

#### Application Default Credentials (ADC)

ADC is the local credential file created by `gcloud auth application-default login`.

On macOS and Linux, it is usually stored here:

```text
~/.config/gcloud/application_default_credentials.json
```

This is the file your local MCP setup usually points to as:

```text
GOOGLE_APPLICATION_CREDENTIALS
```

#### Google Ads developer token

This identifies your Google Ads API access.

It is required for every Google Ads API call.

#### Customer ID

This is the Google Ads account you actually want to query.

Example:

```text
1234567890
```

This is the ID you usually mention in prompts.

#### Manager account ID

This is the Google Ads manager account, also called an MCC account.

If your access to a customer account goes through a manager account, you usually need to set:

```text
GOOGLE_ADS_LOGIN_CUSTOMER_ID
```

Important:

- this should be the **manager account ID**
- not the customer account ID
- use digits only
- remove dashes

Example:

- correct: `1102372421`
- wrong: `110-237-2421`

## Step 1: Create a Google Cloud project

If you already have a Google Cloud account, the first real setup step is to create a project.

### How to create the project

1. Open Google Cloud Console:
   https://console.cloud.google.com/
2. Sign in with your Google account.
3. Click the project selector at the top.
4. Click `New Project`.
5. Enter a project name.
6. Click `Create`.

### What to save

After the project is created:

1. Select the project
2. Copy the **Project ID**
3. Save it somewhere for later

You will need this later as:

```text
GOOGLE_PROJECT_ID
```

## Step 2: Enable the Google Ads API

Once the project exists, you must enable the Google Ads API in that project.

You can do it in the browser, but the terminal is faster and clearer.

Run:

```bash
gcloud config set project YOUR_PROJECT_ID
gcloud services enable googleads.googleapis.com --project YOUR_PROJECT_ID
```

Replace `YOUR_PROJECT_ID` with your actual project ID.

If this step is skipped, the MCP server may be configured correctly but still fail when trying to access Google Ads.

## Step 3: Create an OAuth Client ID

Now create the OAuth credential that your local device will use to log in.

### In Google Cloud Console

1. Open:
   https://console.cloud.google.com/apis/credentials
2. Make sure the correct project is selected
3. Click `Create Credentials`
4. Choose `OAuth client ID`
5. If prompted, configure the consent screen first
6. Choose application type: `Desktop app`
7. Give it a name
8. Click `Create`
9. Download the JSON file

Save that file somewhere on your machine.

You will use it in a later command.

Important:

- this file is your **OAuth client JSON**
- it is not the same as a service account key

## Step 4: Install gcloud, Python, and pipx

If you do not already have them:

### Install gcloud

Follow the official install guide:

https://cloud.google.com/sdk/docs/install

Then verify:

```bash
gcloud --version
```

### Install Python 3

Verify:

```bash
python3 --version
```

### Install pipx

Official docs:

https://pipx.pypa.io/stable/installation/

Then verify:

```bash
pipx --version
```

## Step 5: Get your Google Ads developer token

You need a developer token from Google Ads.

### Where to find it

1. Sign in to your Google Ads account
2. If you use an MCC, sign in to the manager account
3. Open API Center:
   https://ads.google.com/aw/apicenter
4. Copy your developer token

Important:

- a token with test-only access will not work for live ad accounts
- if you see errors about test accounts only, your token access level is the problem

## Step 6: Authenticate your local machine with ADC

This is the most important step in the entire setup.

You need to create local Application Default Credentials with the **Google Ads OAuth scope**.

### Why this matters

By default, local Google Cloud auth often only includes `cloud-platform`.

That is not enough for Google Ads.

You must include this scope:

```text
https://www.googleapis.com/auth/adwords
```

### Run the login command

Run:

```bash
gcloud auth application-default login \
  --scopes https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform \
  --client-id-file=/path/to/your-oauth-client.json
```

Replace `/path/to/your-oauth-client.json` with the actual path to the OAuth client JSON you downloaded in Step 3.

Example:

```bash
gcloud auth application-default login \
  --scopes https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform \
  --client-id-file='/Users/yourname/Downloads/client_secret_1234567890-example.apps.googleusercontent.com.json'
```

### What happens next

1. A browser login flow opens
2. You sign in with the Google account that has Google Ads access
3. Google writes ADC to your local machine

On macOS and Linux, the ADC file is usually created here:

```text
~/.config/gcloud/application_default_credentials.json
```

## Step 7: Verify the ADC scope

Before configuring MCP, verify that your local token actually includes the required Google Ads scope.

Run:

```bash
ACCESS_TOKEN=$(gcloud auth application-default print-access-token) && curl -s "https://oauth2.googleapis.com/tokeninfo?access_token=$ACCESS_TOKEN"
```

You should see `https://www.googleapis.com/auth/adwords` inside the `scope` field.

Example of a correct result:

```json
{
  "scope": "https://www.googleapis.com/auth/adwords https://www.googleapis.com/auth/cloud-platform"
}
```

If `adwords` is missing, stop here and re-run the login command from Step 6.

## Step 8: Add the Google Ads MCP server to your client

The official command used by the MCP server is:

```bash
pipx run --spec git+https://github.com/googleads/google-ads-mcp.git google-ads-mcp
```

The required environment variables are:

- `GOOGLE_APPLICATION_CREDENTIALS`
- `GOOGLE_PROJECT_ID`
- `GOOGLE_ADS_DEVELOPER_TOKEN`

Optional but often required when using a manager account:

- `GOOGLE_ADS_LOGIN_CUSTOMER_ID`

### Codex

Edit:

`~/.codex/config.toml`

Add:

```toml
[mcp_servers.google-ads-mcp]
command = "pipx"
args = ["run", "--spec", "git+https://github.com/googleads/google-ads-mcp.git", "google-ads-mcp"]

[mcp_servers.google-ads-mcp.env]
GOOGLE_APPLICATION_CREDENTIALS = "/Users/yourname/.config/gcloud/application_default_credentials.json"
GOOGLE_PROJECT_ID = "YOUR_PROJECT_ID"
GOOGLE_CLOUD_PROJECT = "YOUR_PROJECT_ID"
GOOGLE_ADS_DEVELOPER_TOKEN = "YOUR_DEVELOPER_TOKEN"
GOOGLE_ADS_LOGIN_CUSTOMER_ID = "YOUR_MANAGER_CUSTOMER_ID"
```

Notes:

- if you have direct access to the target account, you may not need `GOOGLE_ADS_LOGIN_CUSTOMER_ID`
- if you use it, it should be the manager ID with no dashes

### Gemini

Edit:

`~/.gemini/settings.json`

Add:

```json
{
  "mcpServers": {
    "google-ads-mcp": {
      "command": "pipx",
      "args": [
        "run",
        "--spec",
        "git+https://github.com/googleads/google-ads-mcp.git",
        "google-ads-mcp"
      ],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/Users/yourname/.config/gcloud/application_default_credentials.json",
        "GOOGLE_PROJECT_ID": "YOUR_PROJECT_ID",
        "GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID",
        "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "YOUR_MANAGER_CUSTOMER_ID"
      }
    }
  }
}
```

If `settings.json` already contains other keys, merge the `mcpServers` block into the existing JSON instead of replacing the file.

### Claude

For Claude Code, the safer beginner setup is to use the built-in MCP command instead of editing config files by hand.

Run:

```bash
claude mcp add --transport stdio --scope user \
  --env GOOGLE_APPLICATION_CREDENTIALS="/Users/yourname/.config/gcloud/application_default_credentials.json" \
  --env GOOGLE_PROJECT_ID="YOUR_PROJECT_ID" \
  --env GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID" \
  --env GOOGLE_ADS_DEVELOPER_TOKEN="YOUR_DEVELOPER_TOKEN" \
  --env GOOGLE_ADS_LOGIN_CUSTOMER_ID="YOUR_MANAGER_CUSTOMER_ID" \
  google-ads-mcp -- pipx run --spec git+https://github.com/googleads/google-ads-mcp.git google-ads-mcp
```

If you do not use a manager account, omit `GOOGLE_ADS_LOGIN_CUSTOMER_ID`.

You can verify the server was added with:

```bash
claude mcp get google-ads-mcp
```

## Step 9: Restart your MCP client

After editing the config file, fully quit and reopen the client.

Do not rely on hot reload.

Restart:

- Codex
- Gemini
- Claude

This ensures the new MCP server is actually loaded.

## Step 10: Understand which value goes where

This is one of the biggest beginner pain points, so use this table as your quick reference.

| Value | Where it comes from | Where to use it |
| --- | --- | --- |
| Google Cloud project ID | Google Cloud Console | `GOOGLE_PROJECT_ID` and optionally `GOOGLE_CLOUD_PROJECT` |
| ADC file path | Created by `gcloud auth application-default login` | `GOOGLE_APPLICATION_CREDENTIALS` |
| Developer token | Google Ads API Center | `GOOGLE_ADS_DEVELOPER_TOKEN` |
| Manager account ID | Google Ads MCC account | `GOOGLE_ADS_LOGIN_CUSTOMER_ID` |
| Customer ID | Target Google Ads account | In prompts |

Important:

- `GOOGLE_ADS_LOGIN_CUSTOMER_ID` should be the manager account ID, not the customer ID
- use digits only, not dashed IDs like `123-456-7890`
- if the authenticated Google user has direct access to the target account, you may not need `GOOGLE_ADS_LOGIN_CUSTOMER_ID`

Google documents the access model here:

https://developers.google.com/google-ads/api/docs/oauth/access-model

## Step 11: Test the setup

Start with a simple prompt.

### Test 1: basic capability

```text
What can the google-ads-mcp server do?
```

### Test 2: accessible customers

```text
What customers do I have access to?
```

### Test 3: active campaigns in a customer account

```text
How many active campaigns do I have for customer id 1234567890?
```

### Test 4: more detailed reporting

```text
For customer id 1234567890, list active campaigns with campaign name, status, advertising channel type, and today's impressions, clicks, and cost.
```

If these work, your Google Ads MCP setup is functioning correctly.

## Troubleshooting

If the setup fails, check these issues in order.

### Problem: "I don't have the necessary API credentials"

Most likely causes:

- ADC was created without the `adwords` scope
- you signed in with the wrong Google user
- your MCP config points to the wrong credential file

Fix:

1. Re-run:

```bash
gcloud auth application-default login \
  --scopes https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform \
  --client-id-file=/path/to/your-oauth-client.json
```

2. Verify the token scope again with:

```bash
ACCESS_TOKEN=$(gcloud auth application-default print-access-token) && curl -s "https://oauth2.googleapis.com/tokeninfo?access_token=$ACCESS_TOKEN"
```

### Problem: developer token only works with test accounts

Typical error:

```text
The developer token is only approved for use with test accounts
```

Cause:

- your developer token does not yet have production access

Fix:

- check the developer token access level in Google Ads API Center
- apply for the access level you need

Reference:

https://developers.google.com/google-ads/api/docs/api-policy/access-levels

### Problem: wrong file used with --client-id-file

Cause:

- you used a service account key JSON instead of an OAuth client JSON

Fix:

- create an OAuth Client ID in Google Cloud
- download the OAuth client JSON
- use that file with `--client-id-file`

### Problem: wrong manager ID

Cause:

- `GOOGLE_ADS_LOGIN_CUSTOMER_ID` was set to the customer account ID instead of the manager account ID

Fix:

- change it to the manager account ID
- remove dashes

### Problem: IDs include dashes

Cause:

- Google Ads IDs were entered like `123-456-7890`

Fix:

- use `1234567890`

### Problem: Google Ads API not enabled

Cause:

- the Google Ads API was never enabled in the Google Cloud project

Fix:

```bash
gcloud services enable googleads.googleapis.com --project YOUR_PROJECT_ID
```

### Problem: MCP config exists but the client does not see it

Cause:

- the client was not restarted after config changes

Fix:

- fully quit the client
- reopen it

## Security notes

Your config files may contain:

- Google Ads developer token
- credential file paths
- account IDs

Treat these as sensitive values.

Do not commit them into a public repository.

If you accidentally expose them publicly:

- rotate the developer token if necessary
- replace compromised credentials

## Final checklist

Before you start testing, confirm all of the following are true:

- you created a Google Cloud project
- the Google Ads API is enabled in that project
- you created an OAuth Client ID
- you installed `gcloud`
- you installed Python 3 and `pipx`
- you obtained a Google Ads developer token
- you ran `gcloud auth application-default login` with the `adwords` scope
- your token verification shows `https://www.googleapis.com/auth/adwords`
- your MCP client config includes the Google Ads MCP server
- you restarted your MCP client

Once all of that is in place, you are ready to use Google Ads MCP locally.