Connect Codex to Google Ads MCP: Complete Official Setup

This tutorial connects Codex to Google's official open-source Google Ads MCP Server. When you finish, Codex will be able to list accessible Google Ads customer accounts and query campaign performance from a natural-language request.

Google currently provides an official server that you run locally, not a public remote URL that everyone can paste into Codex. The setup therefore includes account and development prerequisites. If you already have a Google Ads Developer Token, allow about 20–40 minutes. Applying for or upgrading the token can require additional waiting time.

What you will have when you finish

• Google Ads appears as connected in Codex's MCP server list.
• Codex can list Customer IDs directly accessible to the authenticated Google user.
• Codex can query the last seven complete calendar days in the target account's time zone and currency.
• The workflow uses the official MCP's reporting capabilities without changing the ad account.

Before you start

What you need	Minimum requirement	How to verify it
Codex	A desktop app with Codex is installed	Start a new Codex chat
Python	Python 3.10 or later	Run python3 --version, or py --version on Windows
pipx	The pipx command is available	Run pipx --version
Google Cloud CLI	The gcloud command is available	Run gcloud --version
Google Ads client account	Your Google user can open the target account	Record its 10-digit Customer ID without hyphens
Google Ads Manager Account	Required to obtain a Developer Token	Confirm that Google Ads API Center opens
Developer Token	Its access level covers the account you will query	Check the token and Access level in API Center
Google Cloud project	You can enable APIs and create an OAuth client	Record the Project ID, not only the display name

Keep the Developer Token, OAuth client file, and Application Default Credentials out of your project, Git repository, and Codex prompts.

Step 1: Confirm the Google Ads account and Developer Token

1.1 Record the client Customer ID

Open the target Google Ads account and find the 10-digit Customer ID in the account selector or upper-right area. Remove hyphens before using it in configuration or prompts:

Shown in the UI: 123-456-7890
Use in config:   1234567890

If you reach the client through a Manager Account, also record the Manager Account's 10-digit Customer ID. You will use it as GOOGLE_ADS_LOGIN_CUSTOMER_ID later.

1.2 Obtain a Developer Token

1. Sign in to a Google Ads Manager Account.
2. Open Google Ads API Center. API Center is not available in a regular client account.
3. If a Developer Token already exists, record its status and Access level.
4. If no token exists, submit the API Access form.

Querying production accounts normally requires Explorer, Basic, or Standard Access. A token with Test Account Access can still complete this tutorial, but only against a Google Ads test account. Do not keep changing the MCP configuration while the token itself is not approved for the target environment.

Checkpoint: You should have a Developer Token, its Access level, the target Customer ID, and, if needed, the Manager Customer ID. See Google's official Developer Token documentation for the current access rules.

Step 2: Install the local tools

The official Google Ads MCP requires Python 3.10 or later and runs through pipx. The ADC sign-in flow also requires the Google Cloud CLI.

macOS

Install Python 3.10 or later. If you use Homebrew, run:

brew install python pipx
pipx ensurepath
brew install --cask google-cloud-sdk

Windows

Install Python 3.10 or later from the official Python download page and select Add Python to PATH in the installer. Then run in PowerShell:

py -m pip install --user pipx
py -m pipx ensurepath

Install gcloud using the Google Cloud CLI instructions for Windows.

Linux

Install Python 3.10 or later and pip through your distribution's package manager, then run:

python3 -m pip install --user pipx
python3 -m pipx ensurepath

Install gcloud using the Google Cloud CLI instructions for Linux.

Close and reopen the terminal after installation, then run:

python3 --version
pipx --version
gcloud --version

Use py --version if Windows does not provide a python3 command. Continue only after all three tools report a version.

Step 3: Prepare Google Cloud and OAuth

3.1 Create a project and enable the Google Ads API

1. Open Google Cloud Console.
2. Create or select a project dedicated to this connection.
3. Copy its Project ID, such as my-ads-analysis-123. The project display name is not a substitute.
4. Open the Google Ads API library page, confirm that the correct project is selected, and select Enable.

3.2 Create a Desktop app OAuth client

1. Open Google Auth Platform in Google Cloud Console.
2. If required, configure the app name, support email, and audience.
3. Add the Google Ads API OAuth scope:

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

4. If the app is in Testing, add the Google account you will use as a Test user.
5. Create an OAuth client with Desktop app as the Application type.
6. Download the client JSON to a private local directory, for example:

/Users/your-name/.config/google-ads/client_secret.json

Do not store the JSON in this project or any folder synchronized to Git.

3.3 Create Application Default Credentials

Replace YOUR_PROJECT_ID with the Project ID:

gcloud config set project YOUR_PROJECT_ID

Replace YOUR_CLIENT_JSON_FILE with the absolute path to the downloaded client file:

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

When the browser opens, sign in as the Google user that can access the target Google Ads account and approve the request. A successful terminal result includes a message like:

Credentials saved to file: [PATH_TO_CREDENTIALS_JSON]

Copy the absolute path inside the brackets for the next step. Do not open or copy the contents of the credential file.

Checkpoint: You should now have PATH_TO_CREDENTIALS_JSON, YOUR_PROJECT_ID, and YOUR_DEVELOPER_TOKEN.

Step 4: Add Google Ads MCP to Codex

1. Open Settings in Codex.
2. Select MCP servers.
3. Select Add server.
4. Enter Google Ads as the Name and select STDIO as the Type.
5. Enter this Command:

pipx

6. Add these four Arguments in order:

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

7. Add the environment variables:

Variable	Value
GOOGLE_APPLICATION_CREDENTIALS	Absolute credential path printed by the ADC command
GOOGLE_PROJECT_ID	Google Cloud Project ID
GOOGLE_ADS_DEVELOPER_TOKEN	Google Ads Developer Token
GOOGLE_ADS_LOGIN_CUSTOMER_ID	Optional; Manager Account ID without hyphens when accessing a client through a manager

8. If the form offers a startup timeout, set it to 120 seconds. On its first launch, pipx must download the server and dependencies from the official GitHub repository.
9. Save the server and select Restart.

If your form does not provide separate argument or environment fields, edit the global ~/.codex/config.toml file:

[mcp_servers.google_ads]
command = "pipx"
args = [
  "run",
  "--spec",
  "git+https://github.com/googleads/google-ads-mcp.git",
  "google-ads-mcp",
]
startup_timeout_sec = 120
tool_timeout_sec = 120
default_tools_approval_mode = "prompt"

[mcp_servers.google_ads.env]
GOOGLE_APPLICATION_CREDENTIALS = "PATH_TO_CREDENTIALS_JSON"
GOOGLE_PROJECT_ID = "YOUR_PROJECT_ID"
GOOGLE_ADS_DEVELOPER_TOKEN = "YOUR_DEVELOPER_TOKEN"
# Uncomment only when accessing a client through a Manager Account:
# GOOGLE_ADS_LOGIN_CUSTOMER_ID = "YOUR_MANAGER_CUSTOMER_ID"

Replace every uppercase placeholder before restarting Codex. This file contains sensitive information and must remain in your local user directory. Do not copy it into a project-level .codex/config.toml or commit it to Git.

Step 5: Confirm that the MCP server is connected

The first launch may take a minute or two. Start a new Codex chat and enter:

/mcp

Find Google Ads, confirm that it is enabled, and look for tools that list customers, search account data, and retrieve resource metadata.

Checkpoint: If the server appears without a startup error, the Python process is working. A server that starts but cannot query data normally points to the next layer: Google credentials or account permissions.

Step 6: List accessible customer accounts

Paste this prompt:

Use only read-only tools from Google Ads MCP to list the Google Ads
Customer IDs directly accessible to the authenticated user.

Return each Customer ID and state whether it is a client or manager account.
If the tool cannot return the account name or type, mark that field
"unavailable" instead of guessing.

Do not create or change any campaign, ad group, ad, keyword, bid, or budget.

Google Ads' accessible-customers method only lists accounts directly available to the user; it does not automatically expand every client below a Manager Account. Seeing the Manager Customer ID but not one of its clients does not necessarily mean authentication failed. In the next request, provide the client Customer ID explicitly and configure GOOGLE_ADS_LOGIN_CUSTOMER_ID.

Step 7: Run your first read-only analysis

Replace 1234567890 with the target client Customer ID without hyphens:

Use only the read-only search tools from Google Ads MCP to analyze
Customer ID 1234567890.

Requirements:
1. First query and confirm customer.id, customer.descriptive_name,
   customer.time_zone, and customer.currency_code.
2. In that account time zone, calculate the last seven complete calendar
   days ending yesterday. State the exact start and end dates and exclude today.
3. By campaign, query campaign.id, campaign.name, campaign.status,
   campaign.advertising_channel_type, metrics.cost_micros,
   metrics.impressions, metrics.clicks, metrics.ctr, metrics.average_cpc,
   metrics.conversions, metrics.cost_per_conversion,
   metrics.conversions_value, and metrics.conversions_value_per_cost.
4. Convert cost_micros and average_cpc from micros to the account currency,
   sort by spend descending, and include totals.
5. If a field is incompatible or unavailable, mark it "unavailable" and
   explain why. Do not replace a missing value with 0 or silently change metrics.
6. Finish with no more than three changes worth human review, but do not
   carry out any optimization.

Do not create or change any campaign, ad group, ad, keyword, bid, or budget.

A reliable first result should show all of the following:

• The target Customer ID and account name.
• The account time zone, currency, and exact start and end dates.
• Values in micros converted to normal currency units.
• Report fields, filters, and unavailable fields.
• Data findings kept separate from execution suggestions.

Troubleshooting in the fastest order

Codex cannot find pipx

Close and reopen Codex and your terminal so the PATH change from pipx ensurepath takes effect. Confirm that pipx --version works in a terminal. On Windows, try py -m pipx --version to determine whether this is only a PATH problem.

The MCP server times out during startup

The first run downloads dependencies from GitHub. Confirm that your network can reach github.com/googleads/google-ads-mcp, keep startup_timeout_sec at 120, and restart. Do not add duplicate copies of the same server.

Google Ads API is not enabled

Open Google Cloud Console, verify that the selected project exactly matches GOOGLE_PROJECT_ID, and enable Google Ads API in that project. Wait a few minutes before retrying.

The Developer Token is approved only for test accounts

The token has Test Account Access. Use a test account for verification or request Explorer, Basic, or Standard Access in API Center. Changing the Customer ID cannot bypass the token's access level.

USER_PERMISSION_DENIED or an empty account list

Confirm that the Google user used for ADC can open the Google Ads account in a browser. The OAuth client, Developer Token, and Google Ads user permission are three different layers. Possessing a Developer Token does not grant access to a client account.

A query through a Manager Account fails

Confirm that GOOGLE_ADS_LOGIN_CUSTOMER_ID is the Manager Customer ID without hyphens and that the prompt uses the actual client Customer ID. Restart Codex after changing an environment variable.

Data is empty or differs from the Google Ads UI

Confirm that the account spent money in the selected dates, then compare the account time zone, conversion actions, attribution context, currency, campaign status, and whether today was excluded. Ask Codex to show the fields and date conditions used in the query.

Credential and execution safety

• Treat the Developer Token, OAuth client JSON, and ADC file like passwords.
• Never paste real tokens or credential contents into prompts, tickets, screenshots, or Git.
• Use the global ~/.codex/config.toml, not a credential-bearing project configuration.
• Reset the Developer Token in Google Ads API Center immediately if it may have leaked.
• This tutorial only queries data. If the server adds write tools in the future, approve each change separately.

Official references

• OpenAI: Connect MCP servers to Codex
• Google: Official Google Ads MCP Server repository
• Google: Obtain and verify a Developer Token
• Google: Google Ads API OAuth and request authorization
• Google: Secure API credentials

After this setup, Codex will launch Google Ads MCP from the saved configuration. Future requests only need the correct Customer ID, complete date range, metrics, and read-only constraint; you do not need to reinstall the server.