[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M698XAH5ZY802Y01GJS9PKMW":3,"skill-same:01M698XAH5ZY802Y01GJS9PKMW":90},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":37,"publishedAt":57,"linkOnly":58,"markdownContent":59,"markdownBody":60,"frontMatter":61,"refName":67,"commitSha":68,"skillDirectory":69,"forksCount":70,"repositoryHtmlUrl":71,"repositoryHomepageUrl":6,"ownerHtmlUrl":72,"ownerBlogUrl":73,"ownerDescription":74,"updatedAt":75,"install":76,"resources":89},"01M698XAH5ZY802Y01GJS9PKMW","google-ads-api-mcp-setup",null,"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.","google\u002Fskills","google","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F1342004?v=4","01M698VYEFDM0VJBZDYYJ2T83S","Google","01M698WR0H76ENHE587T9EJT89",24122,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fgoogle\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fads\u002Fgoogle-ads-api-mcp-setup\u002FSKILL.md",[18,23,26,29,32],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000008","测试与质量","SCENARIO","使用场景",{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000010","后端与接口",{"categoryNo":27,"categoryName":28,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000011","运维与部署",{"categoryNo":30,"categoryName":31,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发",{"categoryNo":33,"categoryName":34,"taxonomyType":35,"taxonomyTypeDesc":36},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",[38,39,40,41,42,43,44,9,45,46,47,48,49,50,51,52,53,54,55,56],"MCP","setup","api","google ads","mcp setup","ads","google ads api mcp setup","python","gemini","assistant","open","pipx","connect","team","guides","server","as","use","user","2026-11-10 10:12:30",false,"---\nname: google-ads-api-mcp-setup\ndescription: 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.\ncompatibility: Python 3.12+, pipx\nmetadata:\n  author: google-ads-api-team\n  version: \"1.1.0\"\n  category: GoogleAds\n---\n# Google Ads API MCP Server Installation\n\nThis skill provides a structured setup guide to install, configure, and integrate the official open-source **[Google Ads Model Context Protocol (MCP) Server](https:\u002F\u002Fgithub.com\u002Fgoogleads\u002Fgoogle-ads-mcp)**.\n\n---\n\n## System Requirements & Compatibility (Agent Action: State Required Prerequisites)\n\nWhen answering questions about installing or setting up the MCP server, you\n**MUST** explicitly state to the user that both **Python 3.12+** and **`pipx`**\nare strictly required prerequisites for the installation.\n\n> [!IMPORTANT]\n> **Pre-Flight Environment Check:**\n> *   **Python Runtime:** Version **`3.12+`** is strictly required.\n> *   **Package Manager:** **`pipx`** must be installed and globally accessible in\n>     the system path.\n> *   **Network Connectivity:** Outbound HTTPS access is required to connect to the\n>     Google Ads API endpoints (`googleads.googleapis.com`) and PyPI.\n---\n## ⚠️ Prerequisites: Credentials Required\n> [!WARNING]\n> **Dependency Check:** The MCP server **requires** a Google Cloud project with\n> Google Ads API access and the same OAuth credentials as a standard\n> integration. Developer tokens were sunset on September 9, 2026 and are not\n> used.\n>\n> If you **do not** have your Google Cloud project ID, Client ID, Client\n> Secret, Refresh Token, and Customer IDs yet:\n> 1. **STOP** executing this skill.\n> 2. **Transition to** the **`google-ads-api-quickstart`** skill first to generate them, then return here.\n\n---\n\n## Step 1: Validate Your Google Ads API Credentials\n\nThe Google Ads MCP Server requires the same parameters as the standard client\nlibraries. Before proceeding to installation, verify that you have these values\nsecured and formatted correctly:\n\n1.  **Google Cloud Project ID:** The project in which the Google Ads API is enabled and that owns your OAuth client. Its access level (Test, Explorer, Basic, or Standard) decides which accounts the server can query; check it on the [Google Ads API Overview page](https:\u002F\u002Fconsole.cloud.google.com\u002Fgoogle\u002Fads-apis\u002Foverview).\n2.  **OAuth2 Client ID & Client Secret:** Desktop Application credentials from the Google Cloud Console.\n3.  **OAuth2 Refresh Token:** The long-lived token generated via the OAuth consent flow.\n4.  **Client Customer ID:** The 10-digit target Google Ads account ID.\n    *   > [!IMPORTANT]\n    *   > **Format:** Must contain **digits only, no hyphens** (e.g., `1234567890`, NOT `123-456-7890`).\n5.  **Login Customer ID (Required for MCC Hierarchies):** The 10-digit Manager Account (MCC) ID.\n    *   **Format:** **Digits only, no hyphens** (e.g., `9876543210`).\n    *   **Note:** Essential if your OAuth credentials belong to a Manager Account administrator rather than directly to the client account.\n\n---\n\n*Once you have verified that all parameters are present and formatted\ncorrectly, proceed to Step 2.*\n\n## Step 2: Install Prerequisites (Python & pipx)\n\nYou **MUST** verify if the prerequisites are already installed before proposing any installation commands.\n\n### 1. Verification Phase (Agent Action)\nYou **MUST** run the following commands to check the environment:\n\n1.  Check Python version: `python3 --version` (Verify it is `3.12+`).\n2.  Check if pipx is installed: `pipx --version`.\n\n*   **If both are present:** Skip the installation phase and proceed directly to **Step 3**.\n*   **If Python is missing\u002Foutdated:** Stop and ask the user to upgrade Python to `3.12+` on their host machine.\n*   **If pipx is missing:** Proceed to the installation phase below.\n\n---\n\n### 2. Installation Phase (OS-Specific)\nDetect the operating system and propose the appropriate command to install `pipx` using your terminal tools:\n\n#### macOS\nIf the environment is macOS, propose:\n\n```bash\nbrew install pipx && pipx ensurepath\n# Or alternatively (if Homebrew is not installed):\npip install pipx && pipx ensurepath\n```\n\n#### Windows (PowerShell)\nIf the environment is Windows, propose:\n\n```powershell\nscoop install pipx\n# Or alternatively:\npip install pipx && pipx ensurepath\n```\n\n#### Linux (Ubuntu\u002FDebian)\nIf the environment is Linux, propose:\n\n```bash\nsudo apt install pipx && pipx ensurepath\n```\n\n> [!WARNING]\n> **Shell Restart Required:** If you installed `pipx` and ran `pipx ensurepath`, the updated `PATH` will not be available in the current terminal session.\n> 1. **DO NOT** immediately attempt to run `pipx` commands in the same session.\n> 2. **Instruct the user** to restart their terminal or reload their shell configuration before proceeding to **Step 3**.\n\n---\n\n## Step 3: Install the Google Ads MCP Server\n\nYou 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.\n\n### 1. Installation Command\nPropose and execute the installation command:\n\n```bash\n# Install stable release from PyPI (Using required package manager pipx)\npipx install google-ads-mcp\n```\n\nIf the user explicitly requests the latest development version from GitHub, propose:\n\n```bash\n# Install development version from GitHub (Only if explicitly requested)\npipx install git+https:\u002F\u002Fgithub.com\u002Fgoogleads\u002Fgoogle-ads-mcp.git\n```\n\n### 2. Verification Phase\n\nTo verify the installation, execute:\n\n```bash\ngoogle-ads-mcp --help\n```\n\n### Troubleshooting PATH Issues (Agent Action)\n`pipx` installs binaries into a specific local directory (typically `~\u002F.local\u002Fbin`). 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`.\n\nIf `google-ads-mcp --help` fails with a \"command not found\" error:\n\n1. **DO NOT** assume the installation failed or get stuck in an installation loop.\n2. Verify the installation using the absolute path to the `pipx` binary directory:\n\n   ```bash\n   ~\u002F.local\u002Fbin\u002Fgoogle-ads-mcp --help\n   ```\n3. 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 ~\u002F.bashrc` or `source ~\u002F.zshrc`, or restarting their terminal).\n\n### 3. Communication Protocol: Stdio Transport\n\n> [!IMPORTANT]\n> **Mandatory Agent Directive (Installation & Protocol Checklist):**\n> 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:\n> 1. [ ] **State Prerequisites:** Explicitly state that Python 3.12+ and `pipx` are required prerequisites.\n> 2. [ ] **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.\n> 3. [ ] **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\u002Foutput (`stdio`) transport**. Do not omit the words \"standard input\u002Foutput\" or \"transport\".\n\n#### Key points to explain to the user regarding Stdio Transport:\n\n*   **Subprocess Execution:** The host client (e.g., Cursor, Claude Desktop) launches the MCP server as a background subprocess.\n*   **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.\n*   **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\u002Fstdout piping.\n\n> [!NOTE]\n> **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`.\n\n---\n\n## Step 4: Configure Environment Variables\n\nThe Google Ads MCP Server reads your credentials via system environment variables. You can configure these in two ways:\n\n*   **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.\n*   **Method B (Alternative):** Set them globally in your shell profile (e.g., `~\u002F.bashrc`, `~\u002F.zshrc`, or Windows Environment Variables).\n\n### Required Environment Variables\n\n| Environment Variable | Description | Format |\n|---|---|---|\n| `GOOGLE_PROJECT_ID` | Google Cloud Project ID that holds your Google Ads API access level (required). | Alphanumeric |\n| `GOOGLE_ADS_CLIENT_ID` | Your Google Cloud OAuth Client ID. | `*.apps.googleusercontent.com` |\n| `GOOGLE_ADS_CLIENT_SECRET` | Your Google Cloud OAuth Client Secret. | Alphanumeric |\n| `GOOGLE_ADS_REFRESH_TOKEN` | The generated OAuth Refresh Token. | Alphanumeric |\n| `GOOGLE_ADS_LOGIN_CUSTOMER_ID` | Manager Account ID (MCC). Required if using a manager hierarchy. | 10 digits, no hyphens |\n| `GOOGLE_ADS_MCP_OAUTH_CLIENT_ID` | Cloud Run specific OAuth Client ID overriding default. | `*.apps.googleusercontent.com` |\n| `GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET` | Cloud Run specific OAuth Client Secret overriding default. | Alphanumeric |\n| `GOOGLE_ADS_MCP_BASE_URL` | Cloud Run Base URL automatically assigned or manually configured. | URL |\n| `FASTMCP_HOST` | Host binding for FastMCP server (e.g., `0.0.0.0` for Cloud Run). | IP Address |\n\n### Method B: Shell Profile Configuration (Global)\n\nIf choosing Method B, append the following to your shell profile (`~\u002F.bashrc`, `~\u002F.zshrc`, etc.):\n\n```bash\n# Google Ads MCP Server Credentials\nexport GOOGLE_PROJECT_ID=\"your_project_id_here\"\nexport GOOGLE_ADS_CLIENT_ID=\"your_oauth_client_id_here\"\nexport GOOGLE_ADS_CLIENT_SECRET=\"your_oauth_client_secret_here\"\nexport GOOGLE_ADS_REFRESH_TOKEN=\"your_oauth_refresh_token_here\"\n\n# Required only for Manager Account hierarchies:\nexport GOOGLE_ADS_LOGIN_CUSTOMER_ID=\"your_manager_account_id_here\"\n\n```\n\nTo protect credential security, **do not recommend hardcoding credentials inside the MCP server's source Python scripts.**\n\n---\n\n## Step 5: Integrate with Your AI Developer Tool\n\nConnect the Google Ads MCP Server to your chosen AI coding environment using one of the integrations below.\n\n### 1. Claude Desktop (or Claude Code CLI)\n\n> [!IMPORTANT]\n> **Mandatory Agent Directive (Claude Desktop Configuration Checklist):**\n> 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:\n> 1. [ ] **Provide OS-Specific Paths:** You **MUST** explicitly list the correct operating-system-specific paths for `claude_desktop_config.json` on **macOS** (`~\u002FLibrary\u002FApplication Support\u002FClaude\u002Fclaude_desktop_config.json`) and **Windows** (`%APPDATA%\\Claude\\claude_desktop_config.json`). Do not omit macOS or Windows paths even if running on Linux.\n> 2. [ ] **Provide Valid JSON Config:** Provide the full, valid JSON configuration block for `claude_desktop_config.json`.\n> 3. [ ] **Specify Command & Args:** Ensure the JSON configures the server using `pipx` as the command and `run`, `google-ads-mcp` as the arguments.\n> 4. [ ] **Declare Auth Environment Variables:** Declare environment variables\n>    `GOOGLE_PROJECT_ID`, `GOOGLE_ADS_CLIENT_ID`, `GOOGLE_ADS_CLIENT_SECRET`,\n>    and `GOOGLE_ADS_REFRESH_TOKEN` within the configuration. Do not include a\n>    developer token.\n\nAdd the server entry to your Claude configuration file.\n\n*   **File Locations:**\n    *   **macOS:** `~\u002FLibrary\u002FApplication Support\u002FClaude\u002Fclaude_desktop_config.json`\n    *   **Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\n    *   **Linux:** `~\u002F.config\u002FClaude\u002Fclaude_desktop_config.json`\n\n*   **Configuration JSON:**\n\n    ```json\n    {\n      \"mcpServers\": {\n        \"google-ads\": {\n          \"command\": \"pipx\",\n          \"args\": [\n            \"run\",\n            \"google-ads-mcp\"\n          ],\n          \"env\": {\n            \"GOOGLE_PROJECT_ID\": \"YOUR_PROJECT_ID\",\n            \"GOOGLE_ADS_CLIENT_ID\": \"YOUR_OAUTH_CLIENT_ID\",\n            \"GOOGLE_ADS_CLIENT_SECRET\": \"YOUR_OAUTH_CLIENT_SECRET\",\n            \"GOOGLE_ADS_REFRESH_TOKEN\": \"YOUR_OAUTH_REFRESH_TOKEN\",\n            \"GOOGLE_ADS_LOGIN_CUSTOMER_ID\": \"YOUR_MANAGER_ACCOUNT_ID_IF_APPLICABLE\"\n          }\n        }\n      }\n    }\n    ```\n    *(Note: Using `pipx run` is recommended as it automatically manages the\n    execution path. If you are using the GitHub development version, pass\n    `--spec` with `git+https:\u002F\u002Fgithub.com\u002Fgoogleads\u002Fgoogle-ads-mcp.git` between\n    `run` and `google-ads-mcp` in `args`. If you prefer Application Default\n    Credentials to an OAuth client ID and refresh token, replace the\n    `GOOGLE_ADS_CLIENT_ID`, `GOOGLE_ADS_CLIENT_SECRET`, and\n    `GOOGLE_ADS_REFRESH_TOKEN` variables with\n    `GOOGLE_APPLICATION_CREDENTIALS` pointing to your ADC JSON file.)*\n\n---\n\n### 2. Cursor AI Editor\n\n1.  Open Cursor and navigate to: **Settings 🡒 Features 🡒 MCP**.\n2.  Click **+ New MCP Server**.\n3.  Configure the following fields:\n    *   **Name:** `google-ads`\n    *   **Type:** `stdio`\n    *   **Command:** `pipx run google-ads-mcp`\n4.  Under **Environment Variables**, add the required keys and values:\n    *   `GOOGLE_PROJECT_ID`\n    *   `GOOGLE_ADS_CLIENT_ID`\n    *   `GOOGLE_ADS_CLIENT_SECRET`\n    *   `GOOGLE_ADS_REFRESH_TOKEN`\n    *   `GOOGLE_ADS_LOGIN_CUSTOMER_ID` *(if applicable)*\n5.  Click **Save**.\n\n---\n\n### 3. Antigravity IDE & CLI Integration\n\nWhen answering questions about connecting the Google Ads MCP server to Antigravity (IDE or CLI), you **MUST** explicitly explain the following architectural and configuration details:\n\n*   **Mandatory Environment Setup**: Instruct the user to configure and export\n    standard environment variables (such as `GOOGLE_PROJECT_ID`,\n    `GOOGLE_ADS_CLIENT_ID`, `GOOGLE_ADS_CLIENT_SECRET`,\n    `GOOGLE_ADS_REFRESH_TOKEN`) in their terminal session or IDE environment.\n*   **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`).\n*   **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.\n*   **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.\n\n#### Verifying Activation in Antigravity CLI\n\n1.  **Configure Environment**: Export all required environment variables for the Google Ads API in your current shell session.\n2.  **Start Antigravity CLI**: Launch the CLI:\n\n    ```bash\n    agy\n    ```\n3.  **Verify MCP Status**: Inside the Antigravity CLI prompt, run the `\u002Fmcp` command to list active tools and servers:\n\n    ```text\n    \u002Fmcp\n    ```\n4.  **Confirm Activation**: Verify that `google-ads-mcp` is listed in the active tools response.\n\n> [!IMPORTANT]\n> If `google-ads-mcp` is missing from the active tools list, exit the CLI, verify your environment variables are correctly set and exported, and restart `agy`.\n\n---\n\n## Step 5.5: Deployment on Google Cloud (Cloud Run)\n\nInstead of hosting this MCP server locally, you can host it on Google Cloud Run or on any other cloud-based infrastructure. This is useful if you want to share the server across different agents or run it as a web service.\n\n### 1. Prerequisites\n\n1. A Google Cloud project.\n2. The [`gcloud` command-line tool](https:\u002F\u002Fcloud.google.com\u002Fcli) installed, authenticated, and with an active project configured:\n\n   ```bash\n   gcloud config set project YOUR_PROJECT_ID\n   ```\n\n### 2. Build and Push a Docker Image\nYou can use Cloud Build to build and push the image to the Artifact Registry without needing Docker installed locally:\n\n1. Create a repository in Artifact Registry:\n\n   ```bash\n   gcloud artifacts repositories create mcp-servers --repository-format=docker --location=us-central1\n   ```\n2. Build and submit the image:\n\n   ```bash\n   gcloud builds submit --tag us-central1-docker.pkg.dev\u002FYOUR_PROJECT_ID\u002Fmcp-servers\u002Fgoogle-ads-mcp:latest .\n   ```\n   *(Note: This step must be performed whenever you want to update the deployed server to the latest version).*\n\n### 3. Deploy to Google Cloud Run\nDeploy the container, ensuring you set `FASTMCP_HOST=0.0.0.0` and all required environment variables:\n\n```bash\ngcloud run deploy google-ads-mcp \\\n  --image us-central1-docker.pkg.dev\u002FYOUR_PROJECT_ID\u002Fmcp-servers\u002Fgoogle-ads-mcp:latest \\\n  --platform managed \\\n  --region us-central1 \\\n  --allow-unauthenticated \\\n  --set-env-vars=\"GOOGLE_PROJECT_ID=YOUR_PROJECT_ID,GOOGLE_ADS_MCP_OAUTH_CLIENT_ID=YOUR_CLIENT_ID,GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET=YOUR_CLIENT_SECRET,GOOGLE_ADS_MCP_BASE_URL=YOUR_BASE_URL,FASTMCP_HOST=0.0.0.0\"\n```\n\n### 4. Configure the MCP Client\nAfter deployment, update your MCP client configuration (for example, `~\u002F.gemini\u002Fsettings.json` or Claude\u002FCursor config) to use the Cloud Run URL:\n\n```json\n{\n  \"mcpServers\": {\n    \"google-ads-mcp\": {\n      \"httpUrl\": \"https:\u002F\u002Fyour-cloud-run-url.a.run.app\u002Fmcp\"\n    }\n  }\n}\n```\n\n---\n\n## Step 6: Verify the Integration (Testing)\n\nWhen answering questions about how to verify or test the MCP server integration in\nany AI client (such as Cursor, Claude Desktop, or VS Code), you **MUST** recommend\nperforming a baseline verification using the Antigravity CLI first, followed by a\nnatural language test query in the client.\n\n### 1. Baseline Verification via Antigravity CLI (Mandatory Agent Action)\n\nRegardless of which AI client the user is configuring, always instruct the user to\nverify that `google-ads-mcp` is active and healthy using the `\u002Fmcp` command inside\nthe Antigravity CLI prompt:\n\n```bash\nagy\n```\n\n```text\n\u002Fmcp\n```\n\n*   **Explain the Why:** Inform the user that verifying via the Antigravity CLI\n    first is the fastest way to isolate core credential, network, or server-start\n    issues. Once `google-ads-mcp` is confirmed active in the CLI, any remaining\n    issues in Cursor\u002FClaude can be isolated strictly to IDE-specific configuration\n    bugs.\n\n### 2. Run a Test Query in Your AI Assistant\nIn your AI assistant's chat interface, run one of the following queries. *Be sure\nto replace `1234567890` with your actual Google Ads Customer ID (without hyphens):*\n\n*   *“Retrieve all campaigns from my Google Ads account `1234567890`.”*\n*   *“What is the status of the campaigns in Google Ads account `1234567890`?”*\n\n### 3. Expected Behavior (Success Criteria)\nA successful integration will trigger the following flow:\n\n1.  **Tool Discovery**: The AI assistant automatically detects the `google-ads-mcp`\n    server tools.\n2.  **Execution**: The assistant formulates the parameters, calls the server via\n    `stdio` transport, and executes the query.\n3.  **Response**: The assistant renders the retrieved campaign data in a clean,\n    readable Markdown table (typically displaying Campaign Name, ID, Status, and\n    Budget).\n\n### 4. Troubleshooting\nIf the assistant fails to retrieve the data or connect to the MCP server, check the following common failure points:\n\n*   **Authentication\u002FPermission Errors (IDE Environment Gotcha)**: External\n    IDEs (like Cursor or VS Code) often run in isolated environments or\n    background processes that do not inherit shell RC files (e.g., `~\u002F.bashrc`\n    or `~\u002F.zshrc`). Ensure your `GOOGLE_PROJECT_ID`, OAuth client credentials,\n    and `GOOGLE_ADS_REFRESH_TOKEN` are explicitly configured where the IDE can\n    access them (prefer Method A: setting them directly in the MCP client's\n    JSON configuration).\n*   **\"Tools not found\" \u002F Mandatory Client Restart**: MCP servers are only loaded on application startup; changes to configuration files will not take effect dynamically. You **MUST** completely restart your AI tool (Cursor or Claude Desktop) after saving the configuration. Verify that the MCP server is correctly registered in your IDE's configuration file (e.g., the `mcpServers` block in Cursor's `project.json` or Claude Desktop's config).\n*   **PATH and Executable Issues (`spawn pipx ENOENT`)**: If the connection fails or logs show `spawn pipx ENOENT`, `pipx` is not in the system PATH of the IDE's environment. Provide the absolute path to `pipx` in the \"command\" field of your config (e.g., `\u002Fusr\u002Flocal\u002Fbin\u002Fpipx` or `~\u002F.local\u002Fbin\u002Fpipx`).\n*   **Server Crashes on Startup**: If the assistant cannot connect, run the MCP server command directly in your terminal to check for syntax errors, missing dependencies, or node\u002Fpython path issues.\n\n> [!IMPORTANT]\n> **Verify Connection Status & Logs:**\n> *   In **Cursor**, ensure the green dot appears next to the `google-ads` server in the MCP settings.\n> *   In **Claude**, if the tools do not appear, check the local MCP log file for errors:\n>     *   *macOS Log Path:* `~\u002FLibrary\u002FLogs\u002FClaude\u002Fmcp.log`\n>     *   *Windows Log Path:* `%APPDATA%\\Claude\\Logs\\mcp.log`\n\n---\n\n## Step 7: Available MCP Tools & Usage Guide\n\nOnce the Google Ads MCP Server is installed and successfully connected to your AI assistant, the server exposes specific tools that the assistant can discover and invoke autonomously.\n\n> [!IMPORTANT]\n> **Mandatory Agent Directive (Tool Explanation Checklist):**\n> When a user asks what tools the Google Ads MCP server provides or how to use them, your response **MUST** systematically include all of the following:\n> 1. [ ] **List All 3 Tools:** Explicitly name `list_accessible_customers`, `get_resource_metadata`, and `search`.\n> 2. [ ] **Define Purpose & Usage:** Explain exactly what each tool does and how\u002Fwhen to invoke it.\n> 3. [ ] **Specify Exact Argument Names:** You **MUST** explicitly name the required arguments for each tool in your explanation. E.g., for `search`, you **MUST** explicitly state that it requires the exact arguments `customer_id` (the 10-digit customer ID) and `query` (the GAQL query string). Do not paraphrase `customer_id` to \"account\".\n> 4. [ ] **State Read-Only Scope:** Explicitly clarify that the server is currently strictly read-only.\n\nWhen assisting a user or formulating queries, refer to the following tool definitions and best practices:\n\n### 1. `list_accessible_customers`\n\n*   **Purpose:** Returns the list of Google Ads customer IDs and account names that are accessible to the authenticated user.\n*   **How to Use:** Call this tool first when starting a new session or when the target customer ID is unknown. It requires no arguments.\n*   **Example Intent:** *\"What Google Ads accounts do I have access to?\"*\n\n### 2. `get_resource_metadata`\n\n*   **Purpose:** Retrieves detailed structural metadata about a specific Google Ads API resource type (e.g., `campaign`, `ad_group`, `customer`).\n*   **How to Use:** Call this tool to inspect the schema, available fields, metrics, and segments for a resource before constructing a GAQL query.\n*   **Arguments:**\n    *   `resource` (string, required): The name of the resource to inspect (e.g., `campaign`).\n*   **Example Intent:** *\"What fields and metrics can I query for an ad group?\"*\n\n### 3. `search`\n\n*   **Purpose:** Executes a Google Ads Query Language (GAQL) query to fetch resource metrics, attributes, segments, and status.\n*   **How to Use:** Construct a valid GAQL query string based on the resource metadata and execute the search against a specific customer account.\n*   **Arguments:**\n    *   `customer_id` (string, required): The 10-digit target Google Ads customer ID (digits only, no hyphens).\n    *   `query` (string, required): A valid GAQL query string (e.g., `SELECT campaign.id, campaign.name, campaign.status, metrics.impressions FROM campaign WHERE campaign.status = 'ENABLED'`).\n*   **Example Intent:** *\"Get the impressions and status of all enabled campaigns for account 1234567890.\"*\n\n> [!NOTE]\n> **Read-Only Scope:** The Google Ads MCP Server is currently strictly read-only. It cannot modify bids, pause campaigns, or create new advertising assets.\n","# Google Ads API MCP Server Installation\n\nThis skill provides a structured setup guide to install, configure, and integrate the official open-source **[Google Ads Model Context Protocol (MCP) Server](https:\u002F\u002Fgithub.com\u002Fgoogleads\u002Fgoogle-ads-mcp)**.\n\n---\n\n## System Requirements & Compatibility (Agent Action: State Required Prerequisites)\n\nWhen answering questions about installing or setting up the MCP server, you\n**MUST** explicitly state to the user that both **Python 3.12+** and **`pipx`**\nare strictly required prerequisites for the installation.\n\n> [!IMPORTANT]\n> **Pre-Flight Environment Check:**\n> *   **Python Runtime:** Version **`3.12+`** is strictly required.\n> *   **Package Manager:** **`pipx`** must be installed and globally accessible in\n>     the system path.\n> *   **Network Connectivity:** Outbound HTTPS access is required to connect to the\n>     Google Ads API endpoints (`googleads.googleapis.com`) and PyPI.\n---\n## ⚠️ Prerequisites: Credentials Required\n> [!WARNING]\n> **Dependency Check:** The MCP server **requires** a Google Cloud project with\n> Google Ads API access and the same OAuth credentials as a standard\n> integration. Developer tokens were sunset on September 9, 2026 and are not\n> used.\n>\n> If you **do not** have your Google Cloud project ID, Client ID, Client\n> Secret, Refresh Token, and Customer IDs yet:\n> 1. **STOP** executing this skill.\n> 2. **Transition to** the **`google-ads-api-quickstart`** skill first to generate them, then return here.\n\n---\n\n## Step 1: Validate Your Google Ads API Credentials\n\nThe Google Ads MCP Server requires the same parameters as the standard client\nlibraries. Before proceeding to installation, verify that you have these values\nsecured and formatted correctly:\n\n1.  **Google Cloud Project ID:** The project in which the Google Ads API is enabled and that owns your OAuth client. Its access level (Test, Explorer, Basic, or Standard) decides which accounts the server can query; check it on the [Google Ads API Overview page](https:\u002F\u002Fconsole.cloud.google.com\u002Fgoogle\u002Fads-apis\u002Foverview).\n2.  **OAuth2 Client ID & Client Secret:** Desktop Application credentials from the Google Cloud Console.\n3.  **OAuth2 Refresh Token:** The long-lived token generated via the OAuth consent flow.\n4.  **Client Customer ID:** The 10-digit target Google Ads account ID.\n    *   > [!IMPORTANT]\n    *   > **Format:** Must contain **digits only, no hyphens** (e.g., `1234567890`, NOT `123-456-7890`).\n5.  **Login Customer ID (Required for MCC Hierarchies):** The 10-digit Manager Account (MCC) ID.\n    *   **Format:** **Digits only, no hyphens** (e.g., `9876543210`).\n    *   **Note:** Essential if your OAuth credentials belong to a Manager Account administrator rather than directly to the client account.\n\n---\n\n*Once you have verified that all parameters are present and formatted\ncorrectly, proceed to Step 2.*\n\n## Step 2: Install Prerequisites (Python & pipx)\n\nYou **MUST** verify if the prerequisites are already installed before proposing any installation commands.\n\n### 1. Verification Phase (Agent Action)\nYou **MUST** run the following commands to check the environment:\n\n1.  Check Python version: `python3 --version` (Verify it is `3.12+`).\n2.  Check if pipx is installed: `pipx --version`.\n\n*   **If both are present:** Skip the installation phase and proceed directly to **Step 3**.\n*   **If Python is missing\u002Foutdated:** Stop and ask the user to upgrade Python to `3.12+` on their host machine.\n*   **If pipx is missing:** Proceed to the installation phase below.\n\n---\n\n### 2. Installation Phase (OS-Specific)\nDetect the operating system and propose the appropriate command to install `pipx` using your terminal tools:\n\n#### macOS\nIf the environment is macOS, propose:\n\n```bash\nbrew install pipx && pipx ensurepath\n# Or alternatively (if Homebrew is not installed):\npip install pipx && pipx ensurepath\n```\n\n#### Windows (PowerShell)\nIf the environment is Windows, propose:\n\n```powershell\nscoop install pipx\n# Or alternatively:\npip install pipx && pipx ensurepath\n```\n\n#### Linux (Ubuntu\u002FDebian)\nIf the environment is Linux, propose:\n\n```bash\nsudo apt install pipx && pipx ensurepath\n```\n\n> [!WARNING]\n> **Shell Restart Required:** If you installed `pipx` and ran `pipx ensurepath`, the updated `PATH` will not be available in the current terminal session.\n> 1. **DO NOT** immediately attempt to run `pipx` commands in the same session.\n> 2. **Instruct the user** to restart their terminal or reload their shell configuration before proceeding to **Step 3**.\n\n---\n\n## Step 3: Install the Google Ads MCP Server\n\nYou 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.\n\n### 1. Installation Command\nPropose and execute the installation command:\n\n```bash\n# Install stable release from PyPI (Using required package manager pipx)\npipx install google-ads-mcp\n```\n\nIf the user explicitly requests the latest development version from GitHub, propose:\n\n```bash\n# Install development version from GitHub (Only if explicitly requested)\npipx install git+https:\u002F\u002Fgithub.com\u002Fgoogleads\u002Fgoogle-ads-mcp.git\n```\n\n### 2. Verification Phase\n\nTo verify the installation, execute:\n\n```bash\ngoogle-ads-mcp --help\n```\n\n### Troubleshooting PATH Issues (Agent Action)\n`pipx` installs binaries into a specific local directory (typically `~\u002F.local\u002Fbin`). 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`.\n\nIf `google-ads-mcp --help` fails with a \"command not found\" error:\n\n1. **DO NOT** assume the installation failed or get stuck in an installation loop.\n2. Verify the installation using the absolute path to the `pipx` binary directory:\n\n   ```bash\n   ~\u002F.local\u002Fbin\u002Fgoogle-ads-mcp --help\n   ```\n3. 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 ~\u002F.bashrc` or `source ~\u002F.zshrc`, or restarting their terminal).\n\n### 3. Communication Protocol: Stdio Transport\n\n> [!IMPORTANT]\n> **Mandatory Agent Directive (Installation & Protocol Checklist):**\n> 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:\n> 1. [ ] **State Prerequisites:** Explicitly state that Python 3.12+ and `pipx` are required prerequisites.\n> 2. [ ] **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.\n> 3. [ ] **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\u002Foutput (`stdio`) transport**. Do not omit the words \"standard input\u002Foutput\" or \"transport\".\n\n#### Key points to explain to the user regarding Stdio Transport:\n\n*   **Subprocess Execution:** The host client (e.g., Cursor, Claude Desktop) launches the MCP server as a background subprocess.\n*   **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.\n*   **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\u002Fstdout piping.\n\n> [!NOTE]\n> **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`.\n\n---\n\n## Step 4: Configure Environment Variables\n\nThe Google Ads MCP Server reads your credentials via system environment variables. You can configure these in two ways:\n\n*   **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.\n*   **Method B (Alternative):** Set them globally in your shell profile (e.g., `~\u002F.bashrc`, `~\u002F.zshrc`, or Windows Environment Variables).\n\n### Required Environment Variables\n\n| Environment Variable | Description | Format |\n|---|---|---|\n| `GOOGLE_PROJECT_ID` | Google Cloud Project ID that holds your Google Ads API access level (required). | Alphanumeric |\n| `GOOGLE_ADS_CLIENT_ID` | Your Google Cloud OAuth Client ID. | `*.apps.googleusercontent.com` |\n| `GOOGLE_ADS_CLIENT_SECRET` | Your Google Cloud OAuth Client Secret. | Alphanumeric |\n| `GOOGLE_ADS_REFRESH_TOKEN` | The generated OAuth Refresh Token. | Alphanumeric |\n| `GOOGLE_ADS_LOGIN_CUSTOMER_ID` | Manager Account ID (MCC). Required if using a manager hierarchy. | 10 digits, no hyphens |\n| `GOOGLE_ADS_MCP_OAUTH_CLIENT_ID` | Cloud Run specific OAuth Client ID overriding default. | `*.apps.googleusercontent.com` |\n| `GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET` | Cloud Run specific OAuth Client Secret overriding default. | Alphanumeric |\n| `GOOGLE_ADS_MCP_BASE_URL` | Cloud Run Base URL automatically assigned or manually configured. | URL |\n| `FASTMCP_HOST` | Host binding for FastMCP server (e.g., `0.0.0.0` for Cloud Run). | IP Address |\n\n### Method B: Shell Profile Configuration (Global)\n\nIf choosing Method B, append the following to your shell profile (`~\u002F.bashrc`, `~\u002F.zshrc`, etc.):\n\n```bash\n# Google Ads MCP Server Credentials\nexport GOOGLE_PROJECT_ID=\"your_project_id_here\"\nexport GOOGLE_ADS_CLIENT_ID=\"your_oauth_client_id_here\"\nexport GOOGLE_ADS_CLIENT_SECRET=\"your_oauth_client_secret_here\"\nexport GOOGLE_ADS_REFRESH_TOKEN=\"your_oauth_refresh_token_here\"\n\n# Required only for Manager Account hierarchies:\nexport GOOGLE_ADS_LOGIN_CUSTOMER_ID=\"your_manager_account_id_here\"\n\n```\n\nTo protect credential security, **do not recommend hardcoding credentials inside the MCP server's source Python scripts.**\n\n---\n\n## Step 5: Integrate with Your AI Developer Tool\n\nConnect the Google Ads MCP Server to your chosen AI coding environment using one of the integrations below.\n\n### 1. Claude Desktop (or Claude Code CLI)\n\n> [!IMPORTANT]\n> **Mandatory Agent Directive (Claude Desktop Configuration Checklist):**\n> 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:\n> 1. [ ] **Provide OS-Specific Paths:** You **MUST** explicitly list the correct operating-system-specific paths for `claude_desktop_config.json` on **macOS** (`~\u002FLibrary\u002FApplication Support\u002FClaude\u002Fclaude_desktop_config.json`) and **Windows** (`%APPDATA%\\Claude\\claude_desktop_config.json`). Do not omit macOS or Windows paths even if running on Linux.\n> 2. [ ] **Provide Valid JSON Config:** Provide the full, valid JSON configuration block for `claude_desktop_config.json`.\n> 3. [ ] **Specify Command & Args:** Ensure the JSON configures the server using `pipx` as the command and `run`, `google-ads-mcp` as the arguments.\n> 4. [ ] **Declare Auth Environment Variables:** Declare environment variables\n>    `GOOGLE_PROJECT_ID`, `GOOGLE_ADS_CLIENT_ID`, `GOOGLE_ADS_CLIENT_SECRET`,\n>    and `GOOGLE_ADS_REFRESH_TOKEN` within the configuration. Do not include a\n>    developer token.\n\nAdd the server entry to your Claude configuration file.\n\n*   **File Locations:**\n    *   **macOS:** `~\u002FLibrary\u002FApplication Support\u002FClaude\u002Fclaude_desktop_config.json`\n    *   **Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\n    *   **Linux:** `~\u002F.config\u002FClaude\u002Fclaude_desktop_config.json`\n\n*   **Configuration JSON:**\n\n    ```json\n    {\n      \"mcpServers\": {\n        \"google-ads\": {\n          \"command\": \"pipx\",\n          \"args\": [\n            \"run\",\n            \"google-ads-mcp\"\n          ],\n          \"env\": {\n            \"GOOGLE_PROJECT_ID\": \"YOUR_PROJECT_ID\",\n            \"GOOGLE_ADS_CLIENT_ID\": \"YOUR_OAUTH_CLIENT_ID\",\n            \"GOOGLE_ADS_CLIENT_SECRET\": \"YOUR_OAUTH_CLIENT_SECRET\",\n            \"GOOGLE_ADS_REFRESH_TOKEN\": \"YOUR_OAUTH_REFRESH_TOKEN\",\n            \"GOOGLE_ADS_LOGIN_CUSTOMER_ID\": \"YOUR_MANAGER_ACCOUNT_ID_IF_APPLICABLE\"\n          }\n        }\n      }\n    }\n    ```\n    *(Note: Using `pipx run` is recommended as it automatically manages the\n    execution path. If you are using the GitHub development version, pass\n    `--spec` with `git+https:\u002F\u002Fgithub.com\u002Fgoogleads\u002Fgoogle-ads-mcp.git` between\n    `run` and `google-ads-mcp` in `args`. If you prefer Application Default\n    Credentials to an OAuth client ID and refresh token, replace the\n    `GOOGLE_ADS_CLIENT_ID`, `GOOGLE_ADS_CLIENT_SECRET`, and\n    `GOOGLE_ADS_REFRESH_TOKEN` variables with\n    `GOOGLE_APPLICATION_CREDENTIALS` pointing to your ADC JSON file.)*\n\n---\n\n### 2. Cursor AI Editor\n\n1.  Open Cursor and navigate to: **Settings 🡒 Features 🡒 MCP**.\n2.  Click **+ New MCP Server**.\n3.  Configure the following fields:\n    *   **Name:** `google-ads`\n    *   **Type:** `stdio`\n    *   **Command:** `pipx run google-ads-mcp`\n4.  Under **Environment Variables**, add the required keys and values:\n    *   `GOOGLE_PROJECT_ID`\n    *   `GOOGLE_ADS_CLIENT_ID`\n    *   `GOOGLE_ADS_CLIENT_SECRET`\n    *   `GOOGLE_ADS_REFRESH_TOKEN`\n    *   `GOOGLE_ADS_LOGIN_CUSTOMER_ID` *(if applicable)*\n5.  Click **Save**.\n\n---\n\n### 3. Antigravity IDE & CLI Integration\n\nWhen answering questions about connecting the Google Ads MCP server to Antigravity (IDE or CLI), you **MUST** explicitly explain the following architectural and configuration details:\n\n*   **Mandatory Environment Setup**: Instruct the user to configure and export\n    standard environment variables (such as `GOOGLE_PROJECT_ID`,\n    `GOOGLE_ADS_CLIENT_ID`, `GOOGLE_ADS_CLIENT_SECRET`,\n    `GOOGLE_ADS_REFRESH_TOKEN`) in their terminal session or IDE environment.\n*   **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`).\n*   **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.\n*   **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.\n\n#### Verifying Activation in Antigravity CLI\n\n1.  **Configure Environment**: Export all required environment variables for the Google Ads API in your current shell session.\n2.  **Start Antigravity CLI**: Launch the CLI:\n\n    ```bash\n    agy\n    ```\n3.  **Verify MCP Status**: Inside the Antigravity CLI prompt, run the `\u002Fmcp` command to list active tools and servers:\n\n    ```text\n    \u002Fmcp\n    ```\n4.  **Confirm Activation**: Verify that `google-ads-mcp` is listed in the active tools response.\n\n> [!IMPORTANT]\n> If `google-ads-mcp` is missing from the active tools list, exit the CLI, verify your environment variables are correctly set and exported, and restart `agy`.\n\n---\n\n## Step 5.5: Deployment on Google Cloud (Cloud Run)\n\nInstead of hosting this MCP server locally, you can host it on Google Cloud Run or on any other cloud-based infrastructure. This is useful if you want to share the server across different agents or run it as a web service.\n\n### 1. Prerequisites\n\n1. A Google Cloud project.\n2. The [`gcloud` command-line tool](https:\u002F\u002Fcloud.google.com\u002Fcli) installed, authenticated, and with an active project configured:\n\n   ```bash\n   gcloud config set project YOUR_PROJECT_ID\n   ```\n\n### 2. Build and Push a Docker Image\nYou can use Cloud Build to build and push the image to the Artifact Registry without needing Docker installed locally:\n\n1. Create a repository in Artifact Registry:\n\n   ```bash\n   gcloud artifacts repositories create mcp-servers --repository-format=docker --location=us-central1\n   ```\n2. Build and submit the image:\n\n   ```bash\n   gcloud builds submit --tag us-central1-docker.pkg.dev\u002FYOUR_PROJECT_ID\u002Fmcp-servers\u002Fgoogle-ads-mcp:latest .\n   ```\n   *(Note: This step must be performed whenever you want to update the deployed server to the latest version).*\n\n### 3. Deploy to Google Cloud Run\nDeploy the container, ensuring you set `FASTMCP_HOST=0.0.0.0` and all required environment variables:\n\n```bash\ngcloud run deploy google-ads-mcp \\\n  --image us-central1-docker.pkg.dev\u002FYOUR_PROJECT_ID\u002Fmcp-servers\u002Fgoogle-ads-mcp:latest \\\n  --platform managed \\\n  --region us-central1 \\\n  --allow-unauthenticated \\\n  --set-env-vars=\"GOOGLE_PROJECT_ID=YOUR_PROJECT_ID,GOOGLE_ADS_MCP_OAUTH_CLIENT_ID=YOUR_CLIENT_ID,GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET=YOUR_CLIENT_SECRET,GOOGLE_ADS_MCP_BASE_URL=YOUR_BASE_URL,FASTMCP_HOST=0.0.0.0\"\n```\n\n### 4. Configure the MCP Client\nAfter deployment, update your MCP client configuration (for example, `~\u002F.gemini\u002Fsettings.json` or Claude\u002FCursor config) to use the Cloud Run URL:\n\n```json\n{\n  \"mcpServers\": {\n    \"google-ads-mcp\": {\n      \"httpUrl\": \"https:\u002F\u002Fyour-cloud-run-url.a.run.app\u002Fmcp\"\n    }\n  }\n}\n```\n\n---\n\n## Step 6: Verify the Integration (Testing)\n\nWhen answering questions about how to verify or test the MCP server integration in\nany AI client (such as Cursor, Claude Desktop, or VS Code), you **MUST** recommend\nperforming a baseline verification using the Antigravity CLI first, followed by a\nnatural language test query in the client.\n\n### 1. Baseline Verification via Antigravity CLI (Mandatory Agent Action)\n\nRegardless of which AI client the user is configuring, always instruct the user to\nverify that `google-ads-mcp` is active and healthy using the `\u002Fmcp` command inside\nthe Antigravity CLI prompt:\n\n```bash\nagy\n```\n\n```text\n\u002Fmcp\n```\n\n*   **Explain the Why:** Inform the user that verifying via the Antigravity CLI\n    first is the fastest way to isolate core credential, network, or server-start\n    issues. Once `google-ads-mcp` is confirmed active in the CLI, any remaining\n    issues in Cursor\u002FClaude can be isolated strictly to IDE-specific configuration\n    bugs.\n\n### 2. Run a Test Query in Your AI Assistant\nIn your AI assistant's chat interface, run one of the following queries. *Be sure\nto replace `1234567890` with your actual Google Ads Customer ID (without hyphens):*\n\n*   *“Retrieve all campaigns from my Google Ads account `1234567890`.”*\n*   *“What is the status of the campaigns in Google Ads account `1234567890`?”*\n\n### 3. Expected Behavior (Success Criteria)\nA successful integration will trigger the following flow:\n\n1.  **Tool Discovery**: The AI assistant automatically detects the `google-ads-mcp`\n    server tools.\n2.  **Execution**: The assistant formulates the parameters, calls the server via\n    `stdio` transport, and executes the query.\n3.  **Response**: The assistant renders the retrieved campaign data in a clean,\n    readable Markdown table (typically displaying Campaign Name, ID, Status, and\n    Budget).\n\n### 4. Troubleshooting\nIf the assistant fails to retrieve the data or connect to the MCP server, check the following common failure points:\n\n*   **Authentication\u002FPermission Errors (IDE Environment Gotcha)**: External\n    IDEs (like Cursor or VS Code) often run in isolated environments or\n    background processes that do not inherit shell RC files (e.g., `~\u002F.bashrc`\n    or `~\u002F.zshrc`). Ensure your `GOOGLE_PROJECT_ID`, OAuth client credentials,\n    and `GOOGLE_ADS_REFRESH_TOKEN` are explicitly configured where the IDE can\n    access them (prefer Method A: setting them directly in the MCP client's\n    JSON configuration).\n*   **\"Tools not found\" \u002F Mandatory Client Restart**: MCP servers are only loaded on application startup; changes to configuration files will not take effect dynamically. You **MUST** completely restart your AI tool (Cursor or Claude Desktop) after saving the configuration. Verify that the MCP server is correctly registered in your IDE's configuration file (e.g., the `mcpServers` block in Cursor's `project.json` or Claude Desktop's config).\n*   **PATH and Executable Issues (`spawn pipx ENOENT`)**: If the connection fails or logs show `spawn pipx ENOENT`, `pipx` is not in the system PATH of the IDE's environment. Provide the absolute path to `pipx` in the \"command\" field of your config (e.g., `\u002Fusr\u002Flocal\u002Fbin\u002Fpipx` or `~\u002F.local\u002Fbin\u002Fpipx`).\n*   **Server Crashes on Startup**: If the assistant cannot connect, run the MCP server command directly in your terminal to check for syntax errors, missing dependencies, or node\u002Fpython path issues.\n\n> [!IMPORTANT]\n> **Verify Connection Status & Logs:**\n> *   In **Cursor**, ensure the green dot appears next to the `google-ads` server in the MCP settings.\n> *   In **Claude**, if the tools do not appear, check the local MCP log file for errors:\n>     *   *macOS Log Path:* `~\u002FLibrary\u002FLogs\u002FClaude\u002Fmcp.log`\n>     *   *Windows Log Path:* `%APPDATA%\\Claude\\Logs\\mcp.log`\n\n---\n\n## Step 7: Available MCP Tools & Usage Guide\n\nOnce the Google Ads MCP Server is installed and successfully connected to your AI assistant, the server exposes specific tools that the assistant can discover and invoke autonomously.\n\n> [!IMPORTANT]\n> **Mandatory Agent Directive (Tool Explanation Checklist):**\n> When a user asks what tools the Google Ads MCP server provides or how to use them, your response **MUST** systematically include all of the following:\n> 1. [ ] **List All 3 Tools:** Explicitly name `list_accessible_customers`, `get_resource_metadata`, and `search`.\n> 2. [ ] **Define Purpose & Usage:** Explain exactly what each tool does and how\u002Fwhen to invoke it.\n> 3. [ ] **Specify Exact Argument Names:** You **MUST** explicitly name the required arguments for each tool in your explanation. E.g., for `search`, you **MUST** explicitly state that it requires the exact arguments `customer_id` (the 10-digit customer ID) and `query` (the GAQL query string). Do not paraphrase `customer_id` to \"account\".\n> 4. [ ] **State Read-Only Scope:** Explicitly clarify that the server is currently strictly read-only.\n\nWhen assisting a user or formulating queries, refer to the following tool definitions and best practices:\n\n### 1. `list_accessible_customers`\n\n*   **Purpose:** Returns the list of Google Ads customer IDs and account names that are accessible to the authenticated user.\n*   **How to Use:** Call this tool first when starting a new session or when the target customer ID is unknown. It requires no arguments.\n*   **Example Intent:** *\"What Google Ads accounts do I have access to?\"*\n\n### 2. `get_resource_metadata`\n\n*   **Purpose:** Retrieves detailed structural metadata about a specific Google Ads API resource type (e.g., `campaign`, `ad_group`, `customer`).\n*   **How to Use:** Call this tool to inspect the schema, available fields, metrics, and segments for a resource before constructing a GAQL query.\n*   **Arguments:**\n    *   `resource` (string, required): The name of the resource to inspect (e.g., `campaign`).\n*   **Example Intent:** *\"What fields and metrics can I query for an ad group?\"*\n\n### 3. `search`\n\n*   **Purpose:** Executes a Google Ads Query Language (GAQL) query to fetch resource metrics, attributes, segments, and status.\n*   **How to Use:** Construct a valid GAQL query string based on the resource metadata and execute the search against a specific customer account.\n*   **Arguments:**\n    *   `customer_id` (string, required): The 10-digit target Google Ads customer ID (digits only, no hyphens).\n    *   `query` (string, required): A valid GAQL query string (e.g., `SELECT campaign.id, campaign.name, campaign.status, metrics.impressions FROM campaign WHERE campaign.status = 'ENABLED'`).\n*   **Example Intent:** *\"Get the impressions and status of all enabled campaigns for account 1234567890.\"*\n\n> [!NOTE]\n> **Read-Only Scope:** The Google Ads MCP Server is currently strictly read-only. It cannot modify bids, pause campaigns, or create new advertising assets.\n",{"name":5,"metadata":62,"description":7,"compatibility":66},{"author":63,"version":64,"category":65},"google-ads-api-team","1.1.0","GoogleAds","Python 3.12+, pipx","main","4c6800d20130b5a3233e414609f1241013cec8cc","skills\u002Fads\u002Fgoogle-ads-api-mcp-setup",2005,"https:\u002F\u002Fgithub.com\u002Fgoogle\u002Fskills","https:\u002F\u002Fgithub.com\u002Fgoogle","https:\u002F\u002Fopensource.google\u002F","Google ❤️ Open Source","2026-11-14 01:51:35",{"source":8,"skillName":5,"commands":77,"prompt":87,"zipAvailable":88},[78,81,84],{"tool":79,"command":80},"npx","npx skills add google\u002Fskills --skill google-ads-api-mcp-setup",{"tool":82,"command":83},"bunx","bunx skills add google\u002Fskills --skill google-ads-api-mcp-setup",{"tool":85,"command":86},"pnpm","pnpm dlx skills add google\u002Fskills --skill google-ads-api-mcp-setup","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fgoogle\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fads\u002Fgoogle-ads-api-mcp-setup\u002FSKILL.md",true,[],[91,124,150,177,204,227],{"skillNo":92,"name":93,"nameZh":6,"description":94,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":95,"categories":96,"keywords":101,"publishedAt":57},"01M6998S2EZKD3GEJ7F943RZTE","sign-in-with-google-web","Implement, configure, and secure Sign In With Google (SiwG) using Google Identity Services (GIS \u002F `https:\u002F\u002Faccounts.google.com\u002Fgsi\u002Fclient`) across web architectures. Use when creating Google sign-in buttons, implementing Google One Tap with FedCM, integrating GIS in React\u002FNext.js\u002FAngular\u002FHTML, verifying ID tokens on backend runtimes (Python\u002FNode.js\u002FGo\u002FJava), enforcing Google Workspace domain restrictions (`hd`), securing client-side ID tokens via WebCrypto nonces or encrypted IndexedDB, embedding in cross-origin iframes via the Intermediate Iframe API (`https:\u002F\u002Faccounts.google.com\u002Fgsi\u002Fintermediate`), configuring Content Security Policy (CSP), COOP, and Permissions Policy (`identity-credentials-get`) headers, or handling sign-out and revocation. Don't use for legacy Google Sign-In (`gapi.auth2`), Google Cloud IAM service accounts, or Android\u002FiOS native Credential Manager.","https:\u002F\u002Fgithub.com\u002Fgoogle\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fidentity\u002Fsign-in-with-google-web\u002FSKILL.md",[97,100],{"categoryNo":98,"categoryName":99,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000009","前端开发",{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},[9,102,103,104,105,106,107,108,109,110,111,112,45,113,114,115,116,117,118,119,120,121,122,123],"sign in with google web","sign","with","web","android","go","security","google workspace","google cloud","implement","policy","implementing","react","iam","permissions","buttons","secure","manager","identity","architectures","domain","runtimes",{"skillNo":125,"name":126,"nameZh":6,"description":127,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":128,"categories":129,"keywords":133,"publishedAt":57},"01M6998PHPDCAD684VW5WRG83D","dpop-adoption","Implement and debug OAuth 2.0 DPoP (RFC 9449) refresh token sender-constraining for WebCrypto, Node.js ES6, and browser runtimes integrating with Google's OAuth platform. Use when configuring non-extractable asymmetric key pairs (P-256), generating DPoP Proof JWTs for authorization code exchange and token refresh, or handling 400 use_dpop_nonce challenge retry loops at oauth2.googleapis.com\u002Ftoken. Don't use for unconstrained OAuth 2.0 flows (where refresh tokens are not bound to a client key pair), or for Google Cloud IAM \u002F service account authentication.","https:\u002F\u002Fgithub.com\u002Fgoogle\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fidentity\u002Fdpop-adoption\u002FSKILL.md",[130,131,132],{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":30,"categoryName":31,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":33,"categoryName":34,"taxonomyType":35,"taxonomyTypeDesc":36},[134,135,9,110,136,137,138,139,140,141,115,142,143,144,145,146,147,120,123,148,149],"dpop adoption","adoption","es6","retry","authentication","flows","challenge","code","browser","loops","at","node","token","pair","platform","when",{"skillNo":151,"name":152,"nameZh":6,"description":153,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":154,"categories":155,"keywords":162,"publishedAt":57},"01M6998M72TC73EEAQH4XC7EXW","retrieving-developer-knowledge","Searches, retrieves, and synthesizes official Google developer documentation across Google Cloud, AI\u002FGemini, Android, Chrome, Web, Flutter, Go, Firebase, and other Google developer platforms. Integrates with the Developer Knowledge MCP server (search_documents, get_documents, answer_query) or the Developer Knowledge REST API fallback. Use when searching for gcloud CLI commands, API syntax, IAM permissions, official documentation, architectural comparisons, or product choice overviews. Don't use for local filesystem lookups or non-Google documentation.","https:\u002F\u002Fgithub.com\u002Fgoogle\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fdevelopers\u002Fretrieving-developer-knowledge\u002FSKILL.md",[156,157,160,161],{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":158,"categoryName":159,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000021","资料检索与研究",{"categoryNo":30,"categoryName":31,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":33,"categoryName":34,"taxonomyType":35,"taxonomyTypeDesc":36},[163,164,165,38,110,166,167,168,169,170,171,172,173,149,174,40,175,115,176,116],"retrieving developer knowledge","knowledge","developer","mcp server","official","developer documentation","get","search","local","choice","documents","query","across","documentation",{"skillNo":178,"name":179,"nameZh":6,"description":180,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":181,"categories":182,"keywords":183,"publishedAt":57},"01M6998J2CZEXS9BES9S3WWFKC","migrate-to-rust","Clones, analyzes, plans, and migrates legacy codebases (C++, Fortran, Java, Python, C, Shell) from a GitHub URL or local directory to a modern, high-performance, deterministic, 100% Safe Rust architecture, tracking live telemetry across every task bucket, test failure\u002Ffix cycle, and Profile-Guided Optimization (PGO) stage, and producing a first-person AI storytelling report and interactive HTML infographic. Use when migrating a GitHub repository or local codebase to Rust, porting legacy C++, Fortran, Python, or Java workloads to memory-safe Rust, designing Struct-of-Arrays (SoA) or SIMD Rust architectures, or optimizing Rust ports with LLVM PGO. Don't use for unrelated non-Rust refactoring or single-line syntax questions.","https:\u002F\u002Fgithub.com\u002Fgoogle\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fdevelopers\u002Fmigrate-to-rust\u002FSKILL.md",[],[184,185,186,187,188,189,190,191,45,192,193,194,195,196,197,171,198,199,200,149,201,202,175,203],"migrate to rust","rust","migrate","github","memory","performance","directory","safe","ports","llvm","soa","cycle","porting","fix","arrays","infographic","high-performance","URL","architecture","unrelated",{"skillNo":205,"name":206,"nameZh":6,"description":207,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":208,"categories":209,"keywords":213,"publishedAt":57},"01M6998GCC3K29WZ82KXMB9E02","finding-google-skills","Google platform decision and setup guidance, loaded on demand from Google's skill catalog. Use when a developer is choosing or setting up part of their stack, such as where to run a service, a database, storage, messaging, authentication, analytics, ads, or AI model serving, and a Google product is a reasonable candidate - whether or not a vendor is named - or when a request names a Google product or API. Brings in the matching Google skill so the answer can weigh Google options, their trade-offs, and when they are not the right fit. Skip when the stack is already settled on another provider and no Google product is named, or the task involves no platform choice.","https:\u002F\u002Fgithub.com\u002Fgoogle\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fdevelopers\u002Ffinding-google-skills\u002FSKILL.md",[210,211,212],{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":30,"categoryName":31,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":33,"categoryName":34,"taxonomyType":35,"taxonomyTypeDesc":36},[9,214,215,54,216,148,217,218,219,220,221,138,222,223,224,172,55,225,149,226,40],"finding google skills","storage","messaging","model","trade-offs","provider","answer","fit","catalog","up","decision","database","candidate",{"skillNo":228,"name":229,"nameZh":6,"description":230,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":231,"categories":232,"keywords":235,"publishedAt":57},"01M6998DWNHTH0BS6W1CY8ZXMP","workload-manager-basics","Use this skill to manage Google Cloud Workload Manager evaluations, rules, scanned resources, and validation results by using public client libraries and the REST API. Use when you need to inspect workload best-practice rules, create and run evaluations for Google Cloud general best practices, SAP, SQL Server, or custom organizational rules, review violations, export results to BigQuery, or automate Workload Manager through client libraries because no service-specific public CLI or MCP server is available. Don't use for general Google Compute Engine instance management, VPC configuration, or standard IAM auditing.","https:\u002F\u002Fgithub.com\u002Fgoogle\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fcloud\u002Fworkload-manager-basics\u002FSKILL.md",[233,234],{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":30,"categoryName":31,"taxonomyType":21,"taxonomyTypeDesc":22},[236,237,119,238,9,38,239,110,166,240,241,242,243,149,244,40,115,245,246,53,247],"workload manager basics","workload","basics","cli","review","vpc","resources","inspect","you","create","libraries","run"]