Google Ads

A tool that connects[Google Adswith Claude AI, allowing you to analyze your advertising data through natural language conversations. This integration gives you access to campaign information, performance metrics, keyword analytics, and ad management—all through simple chat with Claude. ## What Can This Tool Do For Advertising Professionals? - See all your Google Ads accounts in one place - Get account details and basic campaign information - Discover which campaigns are performing best - Track impressions, clicks, conversions, and cost metrics - Analyze performance trends over time - Compare different time periods to spot changes - **Visualize your data**with charts and graphs created by Claude - Identify top and underperforming keywords - Analyze ad copy effectiveness - Check quality scores and competitive metrics - Get actionable insights on how to improve your campaigns - Monitor campaign budgets and spending - Analyze bid strategies and performance - Identify opportunities for optimization - Get recommendations for budget allocation ``` `flowchart TB User(User) -->|Interacts with| Claude Claude(Claude AI Assistant) -->|Makes requests to| MCP](https://ads.google.com/)[Google Ads MCP Server] User -->|Can also use| Cursor[Cursor AI Code Editor] Cursor -->|Makes requests to| MCP subgraph "MCP Server" FastMCP[FastMCP Server] Tools[Available Tools] Auth[Authentication] FastMCP -->|Exposes| Tools FastMCP -->|Uses| Auth end subgraph "Google Ads Tools" ListAccounts[list_accounts] ExecuteGAQL[execute_gaql_query] CampaignPerf[get_campaign_performance] AdPerf[get_ad_performance] RunGAQL[run_gaql] end Tools -->|Includes| ListAccounts Tools -->|Includes| ExecuteGAQL Tools -->|Includes| CampaignPerf Tools -->|Includes| AdPerf Tools -->|Includes| RunGAQL subgraph "Authentication" OAuth[OAuth 2.0 Client ID] ServiceAccount[Service Account] Credentials[Google Ads API Credentials] OAuth -->|Provides| Credentials ServiceAccount -->|Provides| Credentials end MCP -->|Communicates with| GoogleAdsAPI[Google Ads API] GoogleAdsAPI -->|Returns| AdData[Advertising Data] AdData -->|Analyzed by| Claude AdData -->|Visualized by| Claude AdData -->|Can be used by| Cursor Credentials -->|Authorizes| GoogleAdsAPI subgraph "Configuration" EnvVars[Environment Variables] ConfigFiles[Configuration Files] EnvVars -->|Configures| MCP ConfigFiles -->|Configures| Claude ConfigFiles -->|Configures| Cursor end` ``` Here's what you can ask Claude to do once you've set up this integration: The`run_gaql`tool is especially powerful as it allows you to run any custom Google Ads Query Language (GAQL) query. Here are some example queries you can use: ``` `SELECT campaign.name, metrics.clicks, metrics.impressions FROM campaign WHERE segments.date DURING LAST_7DAYS` ``` ``` `SELECT ad_group.name, metrics.conversions, metrics.cost_micros FROM ad_group WHERE metrics.clicks > 100` ``` ``` `SELECT keyword.text, metrics.average_position, metrics.ctr FROM keyword_view ORDER BY metrics.impressions DESC` ``` *For a complete list of all available tools and their detailed descriptions, ask Claude to "list tools" after setup.* ## Getting Started (No Coding Experience Required!) Before using this tool, you'll need to create API credentials that allow Claude to access your Google Ads data. You can choose between two authentication methods: #### Option A: OAuth 2.0 Client ID (User Authentication) Best for individual users or desktop applications: - Go to the[Google Cloud Console - Create a new project or select an existing one - Enable the Google Ads API - Go to "Credentials" → "Create Credentials" → "OAuth Client ID" - Choose "Desktop Application" as the application type - Download the OAuth client configuration file (client_secret.json) - Create a Google Ads API Developer token (see below) #### Option B: Service Account (Server-to-Server Authentication) Better for automated systems or managing multiple accounts: - Go to the](https://console.cloud.google.com/)[Google Cloud Console - Create a new project or select an existing one - Enable the Google Ads API - Go to "Credentials" → "Create Credentials" → "Service Account" - Download the service account key file (JSON) - Grant the service account access to your Google Ads accounts - Create a Google Ads API Developer token (see below) The application now includes robust token refresh handling: - **OAuth 2.0 Tokens**: The tool will automatically refresh expired OAuth tokens when possible, or prompt for re-authentication if the refresh token is invalid. - **Service Account Tokens**: Service account tokens are automatically generated and refreshed as needed without user intervention. - You're building a desktop application - Users need to explicitly grant access - You're managing a single account or a few personal accounts - You want users to have control over access permissions - You're building an automated system - You need server-to-server authentication - You're managing multiple accounts programmatically - You don't want/need user interaction for authentication - You need automatic token refreshing without user intervention Note: Initially, you'll get a test Developer Token that has some limitations. Once you've tested your implementation, you can apply for a production token that removes these restrictions. The`GOOGLE_ADS_LOGIN_CUSTOMER_ID`is optional and is primarily used when: - You're working with a Google Ads Manager Account (MCC) - You need to access multiple client accounts under that manager account The Login Customer ID should be your Manager Account ID (format: XXX-XXX-XXXX) if: - You're accessing multiple accounts under a manager account - You want to use manager account credentials to access client accounts - You're only accessing a single Google Ads account - You're using credentials directly from the account you want to access **🎬 Watch this beginner-friendly tutorial on Youtube:**COMING SOON You'll need to install these tools on your computer: - ](https://console.cloud.google.com/)[Python(version 3.11 or newer) - This runs the connection between Google Ads and Claude - ](https://www.python.org/downloads/)[Node.js- Required for running the MCP inspector and certain MCP components - ](https://nodejs.org/en)[Claude Desktop- The AI assistant you'll chat with Make sure both Python and Node.js are properly installed and available in your system path before proceeding. You need to download this tool to your computer. The easiest way is: - Click the green "Code" button at the top of this page - Select "Download ZIP" - Unzip the downloaded file to a location you can easily find (like your Documents folder) Alternatively, if you're familiar with Git: ``` `git clone https://github.com/ixigo/mcp-google-ads.git` ``` Open your computer's Terminal (Mac) or Command Prompt (Windows): - Navigate to the folder where you unzipped the files: ``` `# Example (replace with your actual path): cd ~/Documents/mcp-google-ads-main` ``` Create a virtual environment (this keeps the project dependencies isolated): ``` `# Using uv (recommended): uv venv .venv # If uv is not installed, install it first: pip install uv # Then create the virtual environment: uv venv .venv # OR using standard Python: python -m venv .venv` ``` **Note:**If you get a "pip not found" error when trying to install uv, see the "If you get 'pip not found' error" section below. ``` `# On Mac/Linux: source .venv/bin/activate # On Windows: .venv\Scripts\activate` ``` ``` `# Using uv: uv pip install -r requirements.txt # OR using standard pip: pip install -r requirements.txt # If you encounter any issues with the MCP package, install it separately: pip install mcp` ``` **If you get "pip not found" error:** ``` `# First ensure pip is installed and updated: python3 -m ensurepip --upgrade python3 -m pip install --upgrade pip # Then try installing the requirements again: python3 -m pip install -r requirements.txt # Or to install uv: python3 -m pip install uv` ``` When you see`(.venv)`at the beginning of your command prompt, it means the virtual environment is active and the dependencies will be installed there without affecting your system Python installation. The Google Ads MCP now supports environment file configuration for easier setup. - Copy the`.env.example`file to`.env`in your project directory: Edit the`.env`file with your actual configuration values: ``` `# Edit the .env file with your favorite text editor # For Mac: nano .env # For Windows: notepad .env` ``` Set the following values in your`.env`file: ``` `# Authentication Type: "oauth" or "service_account" GOOGLE_ADS_AUTH_TYPE=oauth # Path to your credentials file (OAuth client secret or service account key) GOOGLE_ADS_CREDENTIALS_PATH=/path/to/your/credentials.json # Your Google Ads Developer Token GOOGLE_ADS_DEVELOPER_TOKEN=your_developer_token_here # Optional: Manager Account ID (if applicable) GOOGLE_ADS_LOGIN_CUSTOMER_ID=your_manager_account_id` ``` The application will automatically load these values from the`.env`file when it starts. You can also set environment variables directly in your system or in the configuration files for Claude or Cursor: ``` `{ "mcpServers": { "googleAdsServer": { "command": "/FULL/PATH/TO/mcp-google-ads-main/.venv/bin/python", "args": ](https://claude.ai/download)["/FULL/PATH/TO/mcp-google-ads-main/google_ads_server.py"], "env": { "GOOGLE_ADS_AUTH_TYPE": "oauth", "GOOGLE_ADS_CREDENTIALS_PATH": "/FULL/PATH/TO/mcp-google-ads-main/credentials.json", "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN_HERE", "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "YOUR_MANAGER_ACCOUNT_ID_HERE" } } } }` ``` ``` `{ "mcpServers": { "googleAdsServer": { "command": "/FULL/PATH/TO/mcp-google-ads-main/.venv/bin/python", "args": ["/FULL/PATH/TO/mcp-google-ads-main/google_ads_server.py"], "env": { "GOOGLE_ADS_AUTH_TYPE": "oauth", "GOOGLE_ADS_CREDENTIALS_PATH": "/FULL/PATH/TO/mcp-google-ads-main/credentials.json", "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN_HERE", "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "YOUR_MANAGER_ACCOUNT_ID_HERE" } } } }` ``` - Download and install[Claude Desktopif you haven't already - Make sure you have your Google service account credentials file saved somewhere on your computer - Open your computer's Terminal (Mac) or Command Prompt (Windows) and type: ``` `# For Mac users: nano ~/Library/Application\ Support/Claude/claude_desktop_config.json # For Windows users: notepad %APPDATA%\Claude\claude_desktop_config.json` ``` Add the following text (this tells Claude how to connect to Google Ads): ``` `{ "mcpServers": { "googleAdsServer": { "command": "/FULL/PATH/TO/mcp-google-ads-main/.venv/bin/python", "args": ](https://claude.ai/download)["/FULL/PATH/TO/mcp-google-ads-main/google_ads_server.py"], "env": { "GOOGLE_ADS_CREDENTIALS_PATH": "/FULL/PATH/TO/mcp-google-ads-main/service_account_credentials.json", "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN_HERE", "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "YOUR_MANAGER_ACCOUNT_ID_HERE" } } } }` ``` **Important:**Replace all paths and values with the actual information for your account: - The first path should point to the Python executable inside your virtual environment - The second path should point to the`google_ads_server.py`file inside the folder you unzipped - The third path should point to your Google service account credentials JSON file - Add your Google Ads Developer Token - Add your Google Ads Manager Account ID (if applicable) - Mac: - Python path:`/Users/ernesto/Documents/mcp-google-ads/.venv/bin/python` - Script path:`/Users/ernesto/Documents/mcp-google-ads/google_ads_server.py` - Python path:`C:\\Users\\ernesto\\Documents\\mcp-google-ads\\.venv\\Scripts\\python.exe` - Script path:`C:\\Users\\ernesto\\Documents\\mcp-google-ads\\google_ads_server.py` - Mac: Press Ctrl+O, then Enter, then Ctrl+X to exit - Windows: Click File > Save, then close Notepad When Claude opens, you should now see Google Ads tools available in the tools section Cursor is an AI-powered code editor that can be enhanced with MCP tools. You can integrate this Google Ads MCP tool with Cursor to analyze advertising data directly within your coding environment. - If you haven't already, download and install[Cursor **For project-specific configuration:**Create a`.cursor/mcp.json`file in your project directory. **For global configuration (available in all projects):**Create a`~/.cursor/mcp.json`file in your home directory. Add the following configuration to your MCP config file: ``` `{ "mcpServers": { "googleAdsServer": { "command": "/FULL/PATH/TO/mcp-google-ads-main/.venv/bin/python", "args": ](https://cursor.sh/)["/FULL/PATH/TO/mcp-google-ads-main/google_ads_server.py"], "env": { "GOOGLE_ADS_CREDENTIALS_PATH": "/FULL/PATH/TO/mcp-google-ads-main/service_account_credentials.json", "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN_HERE", "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "YOUR_MANAGER_ACCOUNT_ID_HERE" } } } }` ``` **Important:**Replace all paths and values with the actual information for your account, just like in the Claude Desktop configuration. Restart Cursor or reload the workspace to apply the new configuration. The Google Ads MCP will now appear in Cursor's "Available Tools" section and can be used by Cursor's AI agent when needed.