Skip to content
Back to search

mcp-google-ads

An MCP tool that connects Google Ads with Claude AI/Cursor and others, 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, Cursor or Windsurf.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/cohnen--mcp-google-ads/badge.svg)](/listings/cohnen--mcp-google-ads)

HTML

<a href="/listings/cohnen--mcp-google-ads"><img src="/api/listings/cohnen--mcp-google-ads/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Set Up Google Ads API Access

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:

1. Go to the [Google Cloud Console](https://console.cloud.google.com/) 2. Create a new project or select an existing one 3. Enable the Google Ads API 4. Go to "Credentials" → "Create Credentials" → "OAuth Client ID" 5. Choose "Desktop Application" as the application type 6. Download the OAuth client configuration file (client_secret.json) 7. 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:

1. Go to the [Google Cloud Console](https://console.cloud.google.com/) 2. Create a new project or select an existing one 3. Enable the Google Ads API 4. Go to "Credentials" → "Create Credentials" → "Service Account" 5. Download the service account key file (JSON) 6. Grant the service account access to your Google Ads accounts 7. Create a Google Ads API Developer token (see below)

Authentication Token Refreshing

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.

Authentication Method Comparison

Choose OAuth 2.0 Client ID if:

- 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

Choose Service Account if:

- 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

Getting a Developer Token

1. Sign in to your Google Ads account at [https://ads.google.com](https://ads.google.com) 2. Click on Tools & Settings (wrench icon) in the top navigation 3. Under "Setup", click "API Center" 4. If you haven't already, accept the Terms of Service 5. Click "Apply for token" 6. Fill out the application form with details about how you plan to use the API 7. Submit the application and wait for approval (usually 1-3 business days)

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.

Understanding the Login Customer ID

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 can skip this setting if:

- You're only accessing a single Google Ads account - You're using credentials directly from the account you want to access

To find your Manager Account ID:

1. Sign in to your Google Ads Manager Account 2. Click on the settings icon (gear) 3. Your Manager Account ID will be displayed in the format XXX-XXX-XXXX 4. Download the credentials file (a JSON file)

**🎬 Watch this beginner-friendly tutorial on Youtube:** COMING SOON

2. Install Required Software

You'll need to install these tools on your computer:

- [Python](https://www.python.org/downloads/) (version 3.11 or newer) - This runs the connection between Google Ads and Claude

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 711 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. [![MseeP.ai Security Assessment Badge](https://mseep.net/pr/cohnen-mcp-google-ads-badge.png)](https://mseep.ai/app/cohnen-mcp-google-ads)
  2. # Google Ads MCP
  3. ![Google Ads MCP](bg.jpeg)
  4. A tool that connects [Google Ads](https://ads.google.com/) with 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.
  5. ---
  6. ## What Can This Tool Do For Advertising Professionals?
  7. 1. **Account Management**
  8. - See all your Google Ads accounts in one place
  9. - Get account details and basic campaign information
  10. 2. **Campaign Analytics & Reporting**
  11. - Discover which campaigns are performing best
  12. - Track impressions, clicks, conversions, and cost metrics
  13. - Analyze performance trends over time
  14. - Compare different time periods to spot changes
  15. - **Visualize your data** with charts and graphs created by Claude
  16. 3. **Keyword & Ad Performance**
  17. - Identify top and underperforming keywords
  18. - Analyze ad copy effectiveness
  19. - Check quality scores and competitive metrics
  20. - Get actionable insights on how to improve your campaigns
  21. 4. **Budget & Bid Management**
  22. - Monitor campaign budgets and spending
  23. - Analyze bid strategies and performance
  24. - Identify opportunities for optimization
  25. - Get recommendations for budget allocation
  26. ---
  27. ## Google Ads MCP Architecture Flow
  28. ```mermaid
  29. flowchart TB
  30. User(User) -->|Interacts with| Claude
  31. Claude(Claude AI Assistant) -->|Makes requests to| MCP[Google Ads MCP Server]
  32. User -->|Can also use| Cursor[Cursor AI Code Editor]
  33. Cursor -->|Makes requests to| MCP
  34. subgraph "MCP Server"
  35. FastMCP[FastMCP Server]
  36. Tools[Available Tools]
  37. Auth[Authentication]
  38. FastMCP -->|Exposes| Tools
  39. FastMCP -->|Uses| Auth
  40. end
  41. subgraph "Google Ads Tools"
  42. ListAccounts[list_accounts]
  43. ExecuteGAQL[execute_gaql_query]
  44. CampaignPerf[get_campaign_performance]
  45. AdPerf[get_ad_performance]
  46. RunGAQL[run_gaql]
  47. end
  48. Tools -->|Includes| ListAccounts
  49. Tools -->|Includes| ExecuteGAQL
  50. Tools -->|Includes| CampaignPerf
  51. Tools -->|Includes| AdPerf
  52. Tools -->|Includes| RunGAQL
  53. subgraph "Authentication"
  54. OAuth[OAuth 2.0 Client ID]
  55. ServiceAccount[Service Account]
  56. Credentials[Google Ads API Credentials]
  57. OAuth -->|Provides| Credentials
  58. ServiceAccount -->|Provides| Credentials
  59. end
  60. MCP -->|Communicates with| GoogleAdsAPI[Google Ads API]
  61. GoogleAdsAPI -->|Returns| AdData[Advertising Data]
  62. AdData -->|Analyzed by| Claude
  63. AdData -->|Visualized by| Claude
  64. AdData -->|Can be used by| Cursor
  65. Credentials -->|Authorizes| GoogleAdsAPI
  66. subgraph "Configuration"
  67. EnvVars[Environment Variables]
  68. ConfigFiles[Configuration Files]
  69. EnvVars -->|Configures| MCP
  70. ConfigFiles -->|Configures| Claude
  71. ConfigFiles -->|Configures| Cursor
  72. end
  73. ```
  74. ## Available Tools
  75. Here's what you can ask Claude to do once you've set up this integration:
  76. | **What You Can Ask For** | **What It Does** | **What You'll Need to Provide** |
  77. |---------------------------------|-------------------------------------------------------------|----------------------------------------------------------------|
  78. | `list_accounts` | Shows all your Google Ads accounts | Nothing - just ask! |
  79. | `execute_gaql_query` | Runs a Google Ads Query Language query | Your account ID and a GAQL query |
  80. | `get_campaign_performance` | Shows campaign metrics with performance data | Your account ID and time period |
  81. | `get_ad_performance` | Detailed analysis of your ad creative performance | Your account ID and time period |
  82. | `run_gaql` | Runs any arbitrary GAQL query with formatting options | Your account ID, query, and format (table, JSON, or CSV) |
  83. ### Using the Advanced Query Tools
  84. 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:
  85. ### Example 1: Basic campaign metrics
  86. ```sql
  87. SELECT
  88. campaign.name,
  89. metrics.clicks,
  90. metrics.impressions
  91. FROM campaign
  92. WHERE segments.date DURING LAST_7DAYS
  93. ```
  94. ### Example 2: Ad group performance
  95. ```sql
  96. SELECT
  97. ad_group.name,
  98. metrics.conversions,
  99. metrics.cost_micros
  100. FROM ad_group
  101. WHERE metrics.clicks > 100
  102. ```
  103. ### Example 3: Keyword analysis
  104. ```sql
  105. SELECT
  106. keyword.text,
  107. metrics.average_position,
  108. metrics.ctr
  109. FROM keyword_view
  110. ORDER BY metrics.impressions DESC
  111. ```
  112. *For a complete list of all available tools and their detailed descriptions, ask Claude to "list tools" after setup.*
  113. ---
  114. ## Getting Started (No Coding Experience Required!)
  115. ### 1. Set Up Google Ads API Access
  116. 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:
  117. #### Option A: OAuth 2.0 Client ID (User Authentication)
  118. Best for individual users or desktop applications:
  119. 1. Go to the [Google Cloud Console](https://console.cloud.google.com/)
  120. 2. Create a new project or select an existing one
  121. 3. Enable the Google Ads API
  122. 4. Go to "Credentials" → "Create Credentials" → "OAuth Client ID"
  123. 5. Choose "Desktop Application" as the application type
  124. 6. Download the OAuth client configuration file (client_secret.json)
  125. 7. Create a Google Ads API Developer token (see below)
  126. #### Option B: Service Account (Server-to-Server Authentication)
  127. Better for automated systems or managing multiple accounts:
  128. 1. Go to the [Google Cloud Console](https://console.cloud.google.com/)
  129. 2. Create a new project or select an existing one
  130. 3. Enable the Google Ads API
  131. 4. Go to "Credentials" → "Create Credentials" → "Service Account"
  132. 5. Download the service account key file (JSON)
  133. 6. Grant the service account access to your Google Ads accounts
  134. 7. Create a Google Ads API Developer token (see below)
  135. #### Authentication Token Refreshing
  136. The application now includes robust token refresh handling:
  137. - **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.
  138. - **Service Account Tokens**: Service account tokens are automatically generated and refreshed as needed without user intervention.
  139. #### Authentication Method Comparison
  140. Choose OAuth 2.0 Client ID if:
  141. - You're building a desktop application
  142. - Users need to explicitly grant access
  143. - You're managing a single account or a few personal accounts
  144. - You want users to have control over access permissions
  145. Choose Service Account if:
  146. - You're building an automated system
  147. - You need server-to-server authentication
  148. - You're managing multiple accounts programmatically
  149. - You don't want/need user interaction for authentication
  150. - You need automatic token refreshing without user intervention
  151. #### Getting a Developer Token
  152. 1. Sign in to your Google Ads account at [https://ads.google.com](https://ads.google.com)
  153. 2. Click on Tools & Settings (wrench icon) in the top navigation
  154. 3. Under "Setup", click "API Center"
  155. 4. If you haven't already, accept the Terms of Service
  156. 5. Click "Apply for token"
  157. 6. Fill out the application form with details about how you plan to use the API
  158. 7. Submit the application and wait for approval (usually 1-3 business days)
  159. 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.
  160. ### Understanding the Login Customer ID
  161. The `GOOGLE_ADS_LOGIN_CUSTOMER_ID` is optional and is primarily used when:
  162. - You're working with a Google Ads Manager Account (MCC)
  163. - You need to access multiple client accounts under that manager account
  164. The Login Customer ID should be your Manager Account ID (format: XXX-XXX-XXXX) if:
  165. - You're accessing multiple accounts under a manager account
  166. - You want to use manager account credentials to access client accounts
  167. You can skip this setting if:
  168. - You're only accessing a single Google Ads account
  169. - You're using credentials directly from the account you want to access
  170. To find your Manager Account ID:
  171. 1. Sign in to your Google Ads Manager Account
  172. 2. Click on the settings icon (gear)
  173. 3. Your Manager Account ID will be displayed in the format XXX-XXX-XXXX
  174. 4. Download the credentials file (a JSON file)
  175. **🎬 Watch this beginner-friendly tutorial on Youtube:**
  176. COMING SOON
  177. ### 2. Install Required Software
  178. You'll need to install these tools on your computer:
  179. - [Python](https://www.python.org/downloads/) (version 3.11 or newer) - This runs the connection between Google Ads and Claude
  180. - [Node.js](https://nodejs.org/en) - Required for running the MCP inspector and certain MCP components
  181. - [Claude Desktop](https://claude.ai/download) - The AI assistant you'll chat with
  182. Make sure both Python and Node.js are properly installed and available in your system path before proceeding.
  183. ### 3. Download the Google Ads MCP
  184. You need to download this tool to your computer. The easiest way is:
  185. 1. Click the green "Code" button at the top of this page
  186. 2. Select "Download ZIP"
  187. 3. Unzip the downloaded file to a location you can easily find (like your Documents folder)
  188. Alternatively, if you're familiar with Git:
  189. ```bash
  190. git clone https://github.com/ixigo/mcp-google-ads.git
  191. ```
  192. ### 4. Install Required Components
  193. Open your computer's Terminal (Mac) or Command Prompt (Windows):
  194. 1. Navigate to the folder where you unzipped the files:
  195. ```bash
  196. # Example (replace with your actual path):
  197. cd ~/Documents/mcp-google-ads-main
  198. ```
  199. 2. Create a virtual environment (this keeps the project dependencies isolated):
  200. ```bash
  201. # Using uv (recommended):
  202. uv venv .venv
  203. # If uv is not installed, install it first:
  204. pip install uv
  205. # Then create the virtual environment:
  206. uv venv .venv
  207. # OR using standard Python:
  208. python -m venv .venv
  209. ```
  210. **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.
  211. 3. Activate the virtual environment:
  212. ```bash
  213. # On Mac/Linux:
  214. source .venv/bin/activate
  215. # On Windows:
  216. .venv\Scripts\activate
  217. ```
  218. 4. Install the required dependencies:
  219. ```bash
  220. # Using uv:
  221. uv pip install -r requirements.txt
  222. # OR using standard pip:
  223. pip install -r requirements.txt
  224. # If you encounter any issues with the MCP package, install it separately:
  225. pip install mcp
  226. ```
  227. **If you get "pip not found" error:**
  228. ```bash
  229. # First ensure pip is installed and updated:
  230. python3 -m ensurepip --upgrade
  231. python3 -m pip install --upgrade pip
  232. # Then try installing the requirements again:
  233. python3 -m pip install -r requirements.txt
  234. # Or to install uv:
  235. python3 -m pip install uv
  236. ```
  237. 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.
  238. ### 5. Setting Up Environment Configuration
  239. The Google Ads MCP now supports environment file configuration for easier setup.
  240. #### Using .env File (Recommended)
  241. 1. Copy the `.env.example` file to `.env` in your project directory:
  242. ```bash
  243. cp .env.example .env
  244. ```
  245. 2. Edit the `.env` file with your actual configuration values:
  246. ```bash
  247. # Edit the .env file with your favorite text editor
  248. # For Mac:
  249. nano .env
  250. # For Windows:
  251. notepad .env
  252. ```
  253. 3. Set the following values in your `.env` file:
  254. ```
  255. # Authentication Type: "oauth" or "service_account"
  256. GOOGLE_ADS_AUTH_TYPE=oauth
  257. # Path to your credentials file (OAuth client secret or service account key)
  258. GOOGLE_ADS_CREDENTIALS_PATH=/path/to/your/credentials.json
  259. # Your Google Ads Developer Token
  260. GOOGLE_ADS_DEVELOPER_TOKEN=your_developer_token_here
  261. # Optional: Manager Account ID (if applicable)
  262. GOOGLE_ADS_LOGIN_CUSTOMER_ID=your_manager_account_id
  263. ```
  264. 4. Save the file.
  265. The application will automatically load these values from the `.env` file when it starts.
  266. #### Using Direct Environment Variables
  267. You can also set environment variables directly in your system or in the configuration files for Claude or Cursor:
  268. ##### For Claude Desktop
  269. ```json
  270. {
  271. "mcpServers": {
  272. "googleAdsServer": {
  273. "command": "/FULL/PATH/TO/mcp-google-ads-main/.venv/bin/python",
  274. "args": ["/FULL/PATH/TO/mcp-google-ads-main/google_ads_server.py"],
  275. "env": {
  276. "GOOGLE_ADS_AUTH_TYPE": "oauth",
  277. "GOOGLE_ADS_CREDENTIALS_PATH": "/FULL/PATH/TO/mcp-google-ads-main/credentials.json",
  278. "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN_HERE",
  279. "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "YOUR_MANAGER_ACCOUNT_ID_HERE"
  280. }
  281. }
  282. }
  283. }
  284. ```
  285. ##### For Cursor
  286. ```json
  287. {
  288. "mcpServers": {
  289. "googleAdsServer": {
  290. "command": "/FULL/PATH/TO/mcp-google-ads-main/.venv/bin/python",
  291. "args": ["/FULL/PATH/TO/mcp-google-ads-main/google_ads_server.py"],
  292. "env": {
  293. "GOOGLE_ADS_AUTH_TYPE": "oauth",
  294. "GOOGLE_ADS_CREDENTIALS_PATH": "/FULL/PATH/TO/mcp-google-ads-main/credentials.json",
  295. "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN_HERE",
  296. "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "YOUR_MANAGER_ACCOUNT_ID_HERE"
  297. }
  298. }
  299. }
  300. }
  301. ```
  302. ### 6. Connect Claude to Google Ads
  303. 1. Download and install [Claude Desktop](https://claude.ai/download) if you haven't already
  304. 2. Make sure you have your Google service account credentials file saved somewhere on your computer
  305. 3. Open your computer's Terminal (Mac) or Command Prompt (Windows) and type:
  306. ```bash
  307. # For Mac users:
  308. nano ~/Library/Application\ Support/Claude/claude_desktop_config.json
  309. # For Windows users:
  310. notepad %APPDATA%\Claude\claude_desktop_config.json
  311. ```
  312. Add the following text (this tells Claude how to connect to Google Ads):
  313. ```json
  314. {
  315. "mcpServers": {
  316. "googleAdsServer": {
  317. "command": "/FULL/PATH/TO/mcp-google-ads-main/.venv/bin/python",
  318. "args": ["/FULL/PATH/TO/mcp-google-ads-main/google_ads_server.py"],
  319. "env": {
  320. "GOOGLE_ADS_CREDENTIALS_PATH": "/FULL/PATH/TO/mcp-google-ads-main/service_account_credentials.json",
  321. "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN_HERE",
  322. "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "YOUR_MANAGER_ACCOUNT_ID_HERE"
  323. }
  324. }
  325. }
  326. }
  327. ```
  328. **Important:** Replace all paths and values with the actual information for your account:
  329. - The first path should point to the Python executable inside your virtual environment
  330. - The second path should point to the `google_ads_server.py` file inside the folder you unzipped
  331. - The third path should point to your Google service account credentials JSON file
  332. - Add your Google Ads Developer Token
  333. - Add your Google Ads Manager Account ID (if applicable)
  334. Examples:
  335. - Mac:
  336. - Python path: `/Users/ernesto/Documents/mcp-google-ads/.venv/bin/python`
  337. - Script path: `/Users/ernesto/Documents/mcp-google-ads/google_ads_server.py`
  338. - Windows:
  339. - Python path: `C:\\Users\\ernesto\\Documents\\mcp-google-ads\\.venv\\Scripts\\python.exe`
  340. - Script path: `C:\\Users\\ernesto\\Documents\\mcp-google-ads\\google_ads_server.py`
  341. 4. Save the file:
  342. - Mac: Press Ctrl+O, then Enter, then Ctrl+X to exit
  343. - Windows: Click File > Save, then close Notepad
  344. 5. Restart Claude Desktop
  345. 6. When Claude opens, you should now see Google Ads tools available in the tools section
  346. ### 5a. Connect to Cursor (AI Code Editor)
  347. 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.
  348. #### Setting Up Cursor Integration
  349. 1. If you haven't already, download and install [Cursor](https://cursor.sh/)
  350. 2. Create a Cursor MCP configuration file:
  351. **For project-specific configuration:**
  352. Create a `.cursor/mcp.json` file in your project directory.
  353. **For global configuration (available in all projects):**
  354. Create a `~/.cursor/mcp.json` file in your home directory.
  355. 3. Add the following configuration to your MCP config file:
  356. ```json
  357. {
  358. "mcpServers": {
  359. "googleAdsServer": {
  360. "command": "/FULL/PATH/TO/mcp-google-ads-main/.venv/bin/python",
  361. "args": ["/FULL/PATH/TO/mcp-google-ads-main/google_ads_server.py"],
  362. "env": {
  363. "GOOGLE_ADS_CREDENTIALS_PATH": "/FULL/PATH/TO/mcp-google-ads-main/service_account_credentials.json",
  364. "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN_HERE",
  365. "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "YOUR_MANAGER_ACCOUNT_ID_HERE"
  366. }
  367. }
  368. }
  369. }
  370. ```
  371. **Important:** Replace all paths and values with the actual information for your account, just like in the Claude Desktop configuration.
  372. 4. Restart Cursor or reload the workspace to apply the new configuration.
  373. 5. The Google Ads MCP will now appear in Cursor's "Available Tools" section and can be used by Cursor's AI agent when needed.
  374. #### Using Google Ads MCP in Cursor
  375. When working in Cursor, you can ask the AI agent to use the Google Ads tools directly. For example:
  376. - "Use the Google Ads MCP to list all my accounts and show me which ones have the highest spend."
  377. - "Can you analyze my campaign performance for the last 30 days using the Google Ads MCP?"
  378. - "Run a GAQL query to find my top converting keywords using the Google Ads tools."
  379. Cursor will prompt you to approve the tool usage (unless you've enabled Yolo mode) and then display the results directly in the chat interface.
  380. #### Cursor-Specific Features
  381. When using the Google Ads MCP with Cursor, you can:
  382. 1. **Combine Code and Ads Analysis**: Ask Cursor to analyze your marketing-related code alongside actual campaign performance data.
  383. 2. **Generate Data Visualizations**: Request charts and visualizations of your ad performance directly in your development environment.
  384. 3. **Implement Recommendations**: Let Cursor suggest code improvements based on your actual advertising data.
  385. This integration is particularly valuable for developers working on marketing automation, analytics dashboards, or e-commerce applications where ad performance directly impacts code decisions.
  386. ### 6. Start Analyzing Your Advertising Data!
  387. Now you can ask Claude questions about your Google Ads data! Claude can not only retrieve the data but also analyze it, explain trends, and create visualizations to help you understand your advertising performance better.
  388. Here are some powerful prompts you can use with each tool:
  389. | **Tool Name** | **Sample Prompt** |
  390. |---------------------------------|--------------------------------------------------------------------------------------------------|
  391. | `list_accounts` | "List all my Google Ads accounts and tell me which ones have the highest spend this month." |
  392. | `execute_gaql_query` | "Execute this query for account 123-456-7890: SELECT campaign.name, metrics.clicks FROM campaign WHERE metrics.impressions > 1000" |
  393. | `get_campaign_performance` | "Show me the top 10 campaigns for account 123-456-7890 in the last 30 days, highlight any with ROAS below 2, and suggest optimization strategies." |
  394. | `get_ad_performance` | "Do a comprehensive analysis of which ad copy elements are driving the best CTR in my search campaigns and give me actionable recommendations." |
  395. | `run_gaql` | "Run this query and format it as a CSV: SELECT ad_group.name, metrics.clicks, metrics.conversions FROM ad_group WHERE campaign.name LIKE '%Brand%'" |
  396. You can also ask Claude to combine multiple tools and analyze the results. For example:
  397. - "Find my top 20 converting keywords, check their quality scores and impression share, and create a report highlighting opportunities for scaling."
  398. - "Analyze my account's performance trend over the last 90 days, identify my fastest-growing campaigns, and check if there are any budget limitations holding them back."
  399. - "Compare my desktop vs. mobile ad performance, visualize the differences with charts, and recommend specific campaigns that need mobile bid adjustments based on performance gaps."
  400. - "Identify campaigns where I'm spending the most on search terms that aren't in my keyword list, then suggest which ones should be added as exact match keywords."
  401. Claude will use the Google Ads tools to fetch the data, present it in an easy-to-understand format, create visualizations when helpful, and provide actionable insights based on the results.
  402. ---
  403. ## Data Visualization Capabilities
  404. Claude can help you visualize your Google Ads data in various ways:
  405. - **Trend Charts**: See how metrics change over time
  406. - **Comparison Graphs**: Compare different campaigns or ad groups
  407. - **Performance Distributions**: Understand how your ads perform across devices or audiences
  408. - **Correlation Analysis**: Identify relationships between spend and conversion metrics
  409. - **Heatmaps**: Visualize complex datasets with color-coded representations
  410. Simply ask Claude to "visualize" or "create a chart" when analyzing your data, and it will generate appropriate visualizations to help you understand the information better.
  411. ---
  412. ## Troubleshooting
  413. ### Python Command Not Found
  414. On macOS, the default Python command is often `python3` rather than `python`, which can cause issues with some applications including Node.js integrations.
  415. If you encounter errors related to Python not being found, you can create an alias:
  416. 1. Create a Python alias (one-time setup):
  417. ```bash
  418. # For macOS users:
  419. sudo ln -s $(which python3) /usr/local/bin/python
  420. # If that doesn't work, try finding your Python installation:
  421. sudo ln -s /Library/Frameworks/Python.framework/Versions/3.11/bin/python3 /usr/local/bin/python
  422. ```
  423. 2. Verify the alias works:
  424. ```bash
  425. python --version
  426. ```
  427. This creates a symbolic link so that when applications call `python`, they'll actually use your `python3` installation.
  428. ### Claude Configuration Issues
  429. If you're having trouble connecting:
  430. 1. Make sure all file paths in your configuration are correct and use the full path
  431. 2. Check that your service account has access to your Google Ads accounts
  432. 3. Verify that your Developer Token is valid and correctly entered
  433. 4. Restart Claude Desktop after making any changes
  434. 5. Look for error messages in Claude's response when you try to use a tool
  435. 6. Ensure your virtual environment is activated when running the server manually
  436. ### Google Ads API Limitations
  437. If you encounter issues related to API quotas or permissions:
  438. 1. Check your Google Ads API quota limits in the Google Cloud Console
  439. 2. Ensure your Developer Token has the appropriate access level
  440. 3. Verify that you've granted the proper permissions to your service account
  441. ### Other Unexpected Issues
  442. If you encounter any other unexpected issues during installation or usage:
  443. 1. Copy the exact error message you're receiving
  444. 2. Contact Ernesto Cohnen at ernesto@ixigo.com for support, including:
  445. - What you were trying to do
  446. - The exact error message
  447. - Your operating system
  448. - Any steps you've already tried
  449. You can also consult AI assistants which can often help diagnose and resolve technical issues by suggesting specific solutions for your situation.
  450. Remember that most issues have been encountered by others before, and there's usually a straightforward solution available.
  451. ### Testing Your Setup
  452. The repository includes test files that let you verify your Google Ads API connection is working correctly before using it with Claude or Cursor.
  453. #### Testing Basic Functionality
  454. 1. Make sure your virtual environment is activated:
  455. ```bash
  456. # On Mac/Linux:
  457. source .venv/bin/activate
  458. # On Windows:
  459. .venv\Scripts\activate
  460. ```
  461. 2. Configure the environment variables in the test file or set them in your environment:
  462. - Open `test_google_ads_mcp.py` in a text editor
  463. - Find the section starting with `if not os.environ.get("GOOGLE_ADS_CREDENTIALS_PATH"):`
  464. - Update the placeholder values with your actual credentials or comment out this section if you've set them as environment variables
  465. 3. Run the test:
  466. ```bash
  467. python test_google_ads_mcp.py
  468. ```
  469. 4. The test will:
  470. - List all your Google Ads accounts
  471. - Use the first account ID to test campaign performance retrieval
  472. - Test ad performance data
  473. - Retrieve ad creatives
  474. - Run a sample GAQL query
  475. #### Testing Authentication and Token Refresh
  476. To specifically test the authentication and token refresh mechanisms:
  477. 1. Make sure your virtual environment is activated and your `.env` file is configured.
  478. 2. Run the token refresh test:
  479. ```bash
  480. python test_token_refresh.py
  481. ```
  482. 3. This test will:
  483. - Verify that credentials can be loaded from your configured auth type (OAuth or service account)
  484. - Display information about the current token status and expiry
  485. - Test the customer ID formatting function
  486. - For OAuth tokens, attempt to refresh the token and verify it worked
  487. The token refresh test can help confirm that both OAuth and service account credentials are properly configured before using the server with Claude or Cursor.
  488. If all tests complete successfully, your setup is working correctly and ready to use with Claude or Cursor.
  489. ---
  490. ## Contributing
  491. Found a bug or have an idea for improvement? We welcome your input! Open an issue or submit a pull request on GitHub, or contact Ernesto Cohnen directly at [ernesto@ixigo.com](mailto:ernesto@ixigo.com).
  492. ---
  493. ## License
  494. This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
  495. ---
  496. ## About ixigo
  497. ixigo is India's leading travel app, helping millions of travelers find the best deals on flights, trains, buses, and hotels. For more information, visit [ixigo.com](https://www.ixigo.com).
  498. <img src="ixigo-logo.png" alt="ixigo logo" width="200px" />
  499. ixigo is a technology company that builds products to help people find the best deals on flights, trains, buses, and hotels. We're a team of travel enthusiasts who are passionate about making travel more affordable and accessible to everyone.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.