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 . 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: STOP executing this skill. 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: Developer Token: Your unique API access key from the API Center (Manager Account). OAuth2 Client ID & Client Secret: Desktop Application credentials from the Google Cloud Console. OAuth2 Refresh Token: The long-lived token generated via the OAuth consent flow. 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 ). 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: Check Python version: python3 --version (Verify it is 3.12+ ). 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. DO NOT immediately attempt to run pipx commands in the same session. 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: DO NOT assume the installation failed or get stuck in an installation loop. Verify the installation using the absolute path to the pipx binary directory: ~/.local/bin/google-ads-mcp -- help If the absolute path verification succeeds, explain the situation to the user: inform them that the installation was successful but their PATH environment variable needs to be updated by reloading their shell configuration (e.g., running source ~/.bashrc or source ~/.zshrc , or restarting their terminal). 3. Communication Protocol: Stdio Transport [!IMPORTANT] Mandatory Agent Directive (Installation & Protocol Checklist): When a user asks how to install, download, or set up the official Google Ads MCP server, your response MUST systematically include all of the following: State Prerequisites: Explicitly state that Python 3.12+ and pipx are required prerequisites. Provide Official Install Command: Direct the developer to install the official google-ads-mcp package using pipx install google-ads-mcp . Do not suggest third-party unvetted servers. Explain Stdio Transport: You MUST explicitly explain the communication architecture using the exact terminology: state that the MCP server communicates via the Model Context Protocol (MCP) using standard input/output ( stdio ) transport . Do not omit the words "standard input/output" or "transport". Key points to explain to the user regarding Stdio Transport: Subprocess Execution: The host client (e.g., Cursor, Claude Desktop) launches the MCP server as a background subprocess. Command-Line Launch: The host client must be configured with the exact command to run the server ( google-ads-mcp ) and the environment variables containing your Google Ads credentials. No Network Ports: Because it uses stdio , the server does not listen on a network port (like HTTP or WebSockets). Communication is handled entirely via stdin/stdout piping. [!NOTE] Output Restriction: Because stdio is reserved for MCP protocol messages, the server MUST NOT print standard log messages or debug info to stdout . All logging and debugging are routed to stderr . Step 4: Configure Environment Variables The Google Ads MCP Server reads your credentials via system environment variables. You can configure these in two ways: Method A (Recommended): Pass them directly in the MCP client's JSON configuration file (e.g., Cursor or Claude Desktop settings). This isolates the credentials to the specific tool. Method B (Alternative): Set them globally in your shell profile (e.g., ~/.bashrc , ~/.zshrc , or Windows Environment Variables). Required Environment Variables Environment Variable Description Format GOOGLE_ADS_DEVELOPER_TOKEN Your Google Ads Developer Token. Alphanumeric GOOGLE_ADS_CLIENT_ID Your Google Cloud OAuth Client ID. *.apps.googleusercontent.com GOOGLE_ADS_CLIENT_SECRET Your Google Cloud OAuth Client Secret. Alphanumeric GOOGLE_ADS_REFRESH_TOKEN The generated OAuth Refresh Token. Alphanumeric GOOGLE_ADS_LOGIN_CUSTOMER_ID Manager Account ID (MCC). Required if using a manager hierarchy. 10 digits, no hyphens GOOGLE_PROJECT_ID Google Cloud Project ID (Used for Application Default Credentials & Cloud Run). Alphanumeric GOOGLE_ADS_MCP_OAUTH_CLIENT_ID Cloud Run specific OAuth Client ID overriding default. *.apps.googleusercontent.com GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET Cloud Run specific OAuth Client Secret overriding default. Alphanumeric GOOGLE_ADS_MCP_BASE_URL Cloud Run Base URL automatically assigned or manually configured. URL FASTMCP_HOST Host binding for FastMCP server (e.g., 0.0.0.0 for Cloud Run). IP Address Method B: Shell Profile Configuration (Global) If choosing Method B, append the following to your shell profile ( ~/.bashrc , ~/.zshrc , etc.): # Google Ads MCP Server Credentials export GOOGLE_ADS_DEVELOPER_TOKEN= "your_developer_token_here" export GOOGLE_ADS_CLIENT_ID= "your_oauth_client_id_here" export GOOGLE_ADS_CLIENT_SECRET= "your_oauth_client_secret_here" export GOOGLE_ADS_REFRESH_TOKEN= "your_oauth_refresh_token_here" # Required only for Manager Account hierarchies: export GOOGLE_ADS_LOGIN_CUSTOMER_ID= "your_manager_account_id_here" # Required for Application Default Credentials (ADC) or Cloud Run deployments: export GOOGLE_PROJECT_ID= "your_project_id_here" To protect credential security, do not recommend hardcoding credentials inside the MCP server's source Python scripts. Step 5: Integrate with Your AI Developer Tool Connect the Google Ads MCP Server to your chosen AI coding environment using one of the integrations below. 1. Claude Desktop (or Claude Code CLI) [!IMPORTANT] Mandatory Agent Directive (Claude Desktop Configuration Checklist): When a user asks how to configure Claude Desktop or Claude Code to use the Google Ads MCP server, your response MUST systematically include all of the following: Provide OS-Specific Paths: You MUST explicitly list the correct operating-system-specific paths for claude_desktop_config.json on macOS ( ~/Library/Application Support/Claude/claude_desktop_config.json ) and Windows ( %APPDATA%\Claude\claude_desktop_config.json ). Do not omit macOS or Windows paths even if running on Linux. Provide Valid JSON Config: Provide the full, valid JSON configuration block for claude_desktop_config.json . Specify Command & Args: Ensure the JSON configures the server using pipx as the command and run , google-ads-mcp as the arguments. Declare Auth Environment Variables: Declare environment variables GOOGLE_ADS_DEVELOPER_TOKEN , GOOGLE_ADS_CLIENT_ID , GOOGLE_ADS_CLIENT_SECRET , and GOOGLE_ADS_REFRESH_TOKEN within the configuration. Add the server entry to your Claude configuration file. File Locations: macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json Configuration JSON: { "mcpServers" : { "google-ads" : { "command" : "pipx" , "args" : [ "run" , "google-ads-mcp" ] , "env" : { "GOOGLE_ADS_DEVELOPER_TOKEN" : "YOUR_DEVELOPER_TOKEN" , "GOOGLE_ADS_CLIENT_ID" : "YOUR_OAUTH_CLIENT_ID" , "GOOGLE_ADS_CLIENT_SECRET" : "YOUR_OAUTH_CLIENT_SECRET" , "GOOGLE_ADS_REFRESH_TOKEN" : "YOUR_OAUTH_REFRESH_TOKEN" , "GOOGLE_ADS_LOGIN_CUSTOMER_ID" : "YOUR_MANAGER_ACCOUNT_ID_IF_APPLICABLE" } } } } (Note: Using pipx run is recommended as it automatically manages the execution path. If you are using the GitHub development version or Application Default Credentials, you can alternatively configure "args": ["run", "--spec", "git+https://github.com/googleads/google-ads-mcp.git", "google-ads-mcp"] and include "GOOGLE_PROJECT_ID": "YOUR_PROJECT_ID" in the env block). 2. Cursor AI Editor Open Cursor and navigate to: Settings 🡒 Features 🡒 MCP . Click + New MCP Server . Configure the following fields: Name: google-ads Type: stdio Command: pipx run google-ads-mcp Under Environment Variables , add the required keys and values: GOOGLE_ADS_DEVELOPER_TOKEN GOOGLE_ADS_CLIENT_ID GOOGLE_ADS_CLIENT_SECRET GOOGLE_ADS_REFRESH_TOKEN GOOGLE_ADS_LOGIN_CUSTOMER_ID (if applicable) Click Save . 3. Antigravity IDE & CLI Integration When answering questions about connecting the Google Ads MCP server to Antigravity (IDE or CLI), you MUST explicitly explain the following architectural and configuration details: Mandatory Environment Setup : Instruct the user to configure and export standard environment variables (such as GOOGLE_ADS_DEVELOPER_TOKEN , GOOGLE_ADS_CLIENT_ID , GOOGLE_ADS_CLIENT_SECRET , GOOGLE_ADS_REFRESH_TOKEN ) in their terminal session or IDE environment. Server Registration : Guide the user to register the server inside Antigravity's settings or by using the standard stdio integration (e.g., configuring the command pipx run google-ads-mcp ). Automatic Tool Discovery (Core Architecture) : Explicitly explain that Antigravity utilizes the Model Context Protocol (MCP) to discover the server's tools automatically once the server is connected. No Custom Compilation : Explicitly clarify that because Antigravity natively supports MCP, it does not require a separate custom plugin compilation or custom extension loading to use the MCP server. Verifying Activation in Antigravity CLI Configure Environment : Export all required environment variables for the Google Ads API in your current shell session. Start Antigravity CLI : Launch the CLI: agy Verify MCP Status : Inside the Antigravity CLI prompt, run the /mcp command to list active tools and servers: /mcp