Google Ads MCP Setup: Complete Beginner Quickstart

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:

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:

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:

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:

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:

~/.config/gcloud/application_default_credentials.json

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

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:

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:

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:

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:

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:

gcloud --version

Install Python 3

Verify:

python3 --version

Install pipx

Official docs:

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

Then verify:

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:

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

Run the login command

Run:

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:

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:

~/.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:

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:

{
  "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:

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:

[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:

{
  "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:

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:

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.

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

What can the google-ads-mcp server do?

Test 2: accessible customers

What customers do I have access to?

Test 3: active campaigns in a customer account

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

Test 4: more detailed reporting

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:

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:

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:

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:

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.