google/google-ads-api-mcp-setup
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.
npx skills add https://github.com/google/skills --skill google-ads-api-mcp-setupThis skill provides a structured setup guide to install, configure, and integrate the official open-source Google Ads Model Context Protocol (MCP) Server.
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.
> [!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.
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:
1234567890, NOT 123-456-7890).9876543210).*Once you have verified that all five parameters are present and formatted correctly, proceed to Step 2.*
You MUST verify if the prerequisites are already installed before proposing any installation commands.
You MUST run the following commands to check the environment:
python3 --version (Verify it is 3.12+).pipx --version.3.12+ on their host machine.Detect the operating system and propose the appropriate command to install pipx using your terminal tools:
If the environment is macOS, propose:
brew install pipx && pipx ensurepath
# Or alternatively (if Homebrew is not installed):
pip install pipx && pipx ensurepath
If the environment is Windows, propose:
scoop install pipx
# Or alternatively:
pip install pipx && pipx ensurepath
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.
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.
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
To verify the installation, execute:
google-ads-mcp --help
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:
pipx binary directory: ~/.local/bin/google-ads-mcp --help
PATH environment variable needs to be updated by reloading their shell configuration (e.g., running source ~/.bashrc or source ~/.zshrc, or restarting their terminal).> [!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:
> 1. [ ] State Prerequisites: Explicitly state that Python 3.12+ and pipx are required prerequisites.
> 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.
> 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/output (stdio) transport. Do not omit the words "standard input/output" or "transport".
google-ads-mcp) and the environment variables containing your Google Ads credentials.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.
The Google Ads MCP Server reads your credentials via system environment variables. You can configure these in two ways:
~/.bashrc, ~/.zshrc, or Windows 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 |
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.
Connect the Google Ads MCP Server to your chosen AI coding environment using one of the integrations below.
> [!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:
> 1. [ ] 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.
> 2. [ ] Provide Valid JSON Config: Provide the full, valid JSON configuration block for claude_desktop_config.json.
> 3. [ ] Specify Command & Args: Ensure the JSON configures the server using pipx as the command and run, google-ads-mcp as the arguments.
> 4. [ ] 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.
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.json~/.config/Claude/claude_desktop_config.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).*
google-adsstdiopipx run google-ads-mcpGOOGLE_ADS_DEVELOPER_TOKENGOOGLE_ADS_CLIENT_IDGOOGLE_ADS_CLIENT_SECRETGOOGLE_ADS_REFRESH_TOKENGOOGLE_ADS_LOGIN_CUSTOMER_ID *(if applicable)*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:
GOOGLE_ADS_DEVELOPER_TOKEN, GOOGLE_ADS_CLIENT_ID, GOOGLE_ADS_CLIENT_SECRET, GOOGLE_ADS_REFRESH_TOKEN) in their terminal session or IDE environment.stdio integration (e.g., configuring the command pipx run google-ads-mcp). agy
/mcp command to list active tools and servers: /mcp
google-ads-mcp is listed in the active tools response.> [!IMPORTANT]
> 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.
Instead 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.
gcloud command-line tool installed, authenticated, and with an active project configured: gcloud config set project YOUR_PROJECT_ID
You can use Cloud Build to build and push the image to the Artifact Registry without needing Docker installed locally:
gcloud artifacts repositories create mcp-servers --repository-format=docker --location=us-central1
gcloud builds submit --tag us-central1-docker.pkg.dev/YOUR_PROJECT_ID/mcp-servers/google-ads-mcp:latest .
*(Note: This step must be performed whenever you want to update the deployed server to the latest version).*
Deploy the container, ensuring you set FASTMCP_HOST=0.0.0.0 and all required environment variables:
gcloud run deploy google-ads-mcp \
--image us-central1-docker.pkg.dev/YOUR_PROJECT_ID/mcp-servers/google-ads-mcp:latest \
--platform managed \
--region us-central1 \
--allow-unauthenticated \
--set-env-vars="GOOGLE_PROJECT_ID=YOUR_PROJECT_ID,GOOGLE_ADS_DEVELOPER_TOKEN=YOUR_DEVELOPER_TOKEN,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"
After deployment, update your MCP client configuration (for example, ~/.gemini/settings.json or Claude/Cursor config) to use the Cloud Run URL:
{
"mcpServers": {
"google-ads-mcp": {
"httpUrl": "https://your-cloud-run-url.a.run.app/mcp"
}
}
}
When answering questions about how to verify or test the MCP server integration in
any AI client (such as Cursor, Claude Desktop, or VS Code), you MUST recommend
performing a baseline verification using the Antigravity CLI first, followed by a
natural language test query in the client.
Regardless of which AI client the user is configuring, always instruct the user to
verify that google-ads-mcp is active and healthy using the /mcp command inside
the Antigravity CLI prompt:
agy
/mcp
first is the fastest way to isolate core credential, network, or server-start
issues. Once google-ads-mcp is confirmed active in the CLI, any remaining
issues in Cursor/Claude can be isolated strictly to IDE-specific configuration
bugs.
In your AI assistant's chat interface, run one of the following queries. *Be sure
to replace 1234567890 with your actual Google Ads Customer ID (without hyphens):*
1234567890.”*1234567890?”*A successful integration will trigger the following flow:
google-ads-mcpserver tools.
stdio transport, and executes the query.
readable Markdown table (typically displaying Campaign Name, ID, Status, and
Budget).
If the assistant fails to retrieve the data or connect to the MCP server, check the following common failure points:
~/.bashrc or ~/.zshrc). Ensure your GOOGLE_ADS_DEVELOPER_TOKEN, OAuth client credentials, and GOOGLE_ADS_REFRESH_TOKEN are explicitly configured where the IDE can access them (prefer Method A: setting them directly in the MCP client's JSON configuration).mcpServers block in Cursor's project.json or Claude Desktop's config).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., /usr/local/bin/pipx or ~/.local/bin/pipx).> [!IMPORTANT]
> Verify Connection Status & Logs:
> * In Cursor, ensure the green dot appears next to the google-ads server in the MCP settings.
> * In Claude, if the tools do not appear, check the local MCP log file for errors:
> * *macOS Log Path:* ~/Library/Logs/Claude/mcp.log
> * *Windows Log Path:* %APPDATA%\Claude\Logs\mcp.log
Once 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.
> [!IMPORTANT]
> Mandatory Agent Directive (Tool Explanation Checklist):
> 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:
> 1. [ ] List All 3 Tools: Explicitly name list_accessible_customers, get_resource_metadata, and search.
> 2. [ ] Define Purpose & Usage: Explain exactly what each tool does and how/when to invoke it.
> 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".
> 4. [ ] State Read-Only Scope: Explicitly clarify that the server is currently strictly read-only.
When assisting a user or formulating queries, refer to the following tool definitions and best practices:
list_accessible_customersget_resource_metadatacampaign, ad_group, customer).resource (string, required): The name of the resource to inspect (e.g., campaign).searchcustomer_id (string, required): The 10-digit target Google Ads customer ID (digits only, no hyphens).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').> [!NOTE]
> Read-Only Scope: The Google Ads MCP Server is currently strictly read-only. It cannot modify bids, pause campaigns, or create new advertising assets.
Take google/google-ads-api-mcp-setup from the repository into ~/.claude/skills for personal
use, or into .claude/skills inside a project.
The agent identifies a skill by the name field in its header. Two skills with the
same name cannot sit side by side — one of them will be ignored.
The instructions reference pip, brew.
Without those the skill loads but fails at the first command.