/google-ads-api-mcp-setup

name: google-ads-api-mcp-setup
description: Guides developers through downloading, configuring, and installing the official open-source Google Ads MCP Server. Use this skill when a user wants to connect their AI assistant (such as Gemini, Claude Code, or Cursor) to their Google Ads account to query campaigns or retrieve reporting metrics using natural language.
compatibility: Python 3.12+, pipx
metadata:
  author: google-ads-api-team
  version: "1.0"
  category: GoogleAds

Google Ads API MCP Server Installation

This skill provides a structured setup guide to install, configure, and integrate the official open-source **[Google Ads Model Context Protocol (MCP) Server](https://github.com/googleads/google-ads-mcp)**.

---

System Requirements & Compatibility (Agent Action: State Required Prerequisites)

When answering questions about installing or setting up the MCP server, you **MUST** explicitly state to the user that both **Python 3.12+** and **`pipx`** are strictly required prerequisites for the installation.

> [!IMPORTANT] > **Pre-Flight Environment Check:** > * **Python Runtime:** Version **`3.12+`** is strictly required. > * **Package Manager:** **`pipx`** must be installed and globally accessible in > the system path. > * **Network Connectivity:** Outbound HTTPS access is required to connect to the > Google Ads API endpoints (`googleads.googleapis.com`) and PyPI. ---

⚠️ Prerequisites: Credentials Required

> [!WARNING] > **Dependency Check:** The MCP server **requires** the same 5 authentication credentials as a standard integration. > > If you **do not** have your Developer Token, Client ID, Client Secret, Refresh Token, and Customer IDs yet: > 1. **STOP** executing this skill. > 2. **Transition to** the **`google-ads-api-quickstart`** skill first to generate them, then return here.

---

Step 1: Validate Your Google Ads API Credentials

The Google Ads MCP Server requires the same five parameters as the standard client libraries. Before proceeding to installation, verify that you have these values secured and formatted correctly:

1. **Developer Token:** Your unique API access key from the **API Center** (Manager Account). 2. **OAuth2 Client ID & Client Secret:** Desktop Application credentials from the Google Cloud Console. 3. **OAuth2 Refresh Token:** The long-lived token generated via the OAuth consent flow. 4. **Client Customer ID:** The 10-digit target Google Ads account ID.

• > [!IMPORTANT]
• > **Format:** Must contain **digits only, no hyphens** (e.g., `1234567890`, NOT `123-456-7890`).

5. **Login Customer ID (Required for MCC Hierarchies):** The 10-digit Manager Account (MCC) ID.

• **Format:** **Digits only, no hyphens** (e.g., `9876543210`).
• **Note:** Essential if your OAuth credentials belong to a Manager Account administrator rather than directly to the client account.

---

*Once you have verified that all five parameters are present and formatted correctly, proceed to Step 2.*

Step 2: Install Prerequisites (Python & pipx)

You **MUST** verify if the prerequisites are already installed before proposing any installation commands.

1. Verification Phase (Agent Action)

You **MUST** run the following commands to check the environment:

1. Check Python version: `python3 --version` (Verify it is `3.12+`). 2. Check if pipx is installed: `pipx --version`.

• **If both are present:** Skip the installation phase and proceed directly to **Step 3**.
• **If Python is missing/outdated:** Stop and ask the user to upgrade Python to `3.12+` on their host machine.
• **If pipx is missing:** Proceed to the installation phase below.

---

2. Installation Phase (OS-Specific)

Detect the operating system and propose the appropriate command to install `pipx` using your terminal tools:

macOS

If the environment is macOS, propose:

brew install pipx && pipx ensurepath
# Or alternatively (if Homebrew is not installed):
pip install pipx && pipx ensurepath

Windows (PowerShell)

If the environment is Windows, propose:

scoop install pipx
# Or alternatively:
pip install pipx && pipx ensurepath

Linux (Ubuntu/Debian)

If the environment is Linux, propose:

sudo apt install pipx && pipx ensurepath

> [!WARNING] > **Shell Restart Required:** If you installed `pipx` and ran `pipx ensurepath`, the updated `PATH` will not be available in the current terminal session. > 1. **DO NOT** immediately attempt to run `pipx` commands in the same session. > 2. **Instruct the user** to restart their terminal or reload their shell configuration before proceeding to **Step 3**.

---

Step 3: Install the Google Ads MCP Server

You must install the server package. By default, you **MUST** install the stable release from PyPI. Only install the GitHub development version if the user explicitly requests it.

1. Installation Command

Propose and execute the installation command:

# Install stable release from PyPI (Using required package manager pipx)
pipx install google-ads-mcp

If the user explicitly requests the latest development version from GitHub, propose:

# Install development version from GitHub (Only if explicitly requested)
pipx install git+https://github.com/googleads/google-ads-mcp.git

2. Verification Phase

To verify the installation, execute:

google-ads-mcp --help

Troubleshooting PATH Issues (Agent Action)

`pipx` installs binaries into a specific local directory (typically `~/.local/bin`). If the user's shell configuration (e.g., `.bashrc` or `.zshrc`) hasn't been reloaded, `google-ads-mcp` might not be found in the current `PATH`.

If `google-ads-mcp --help` fails with a "command not found" error:

1. **DO NOT** assume the installation failed or get stuck in an installation loop. 2. Verify the installation using the absolute path to the `pipx` binary directory:

   ~/.local/bin/google-ads-mcp --help

3.