Skip to content
Back to search

google-ads-mcp-server

This repo helps us to analyze googla ads performance data

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/gomarble-ai--google-ads-mcp-server/badge.svg)](/listings/gomarble-ai--google-ads-mcp-server)

HTML

<a href="/listings/gomarble-ai--google-ads-mcp-server"><img src="/api/listings/gomarble-ai--google-ads-mcp-server/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.

3.1 Clone and Install

# Clone the repository
git clone https://github.com/yourusername/google-ads-mcp-server.git
cd google-ads-mcp-server

# Create virtual environment (recommended)
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

3.2 Environment Configuration

Create a `.env` file in your project directory:

# Copy the example file
cp .env.example .env

Edit `.env` with your credentials:

# Required: Google Ads API Developer Token
GOOGLE_ADS_DEVELOPER_TOKEN=your_developer_token_here

# Required: Path to OAuth credentials JSON file (downloaded from Google Cloud)
GOOGLE_ADS_OAUTH_CONFIG_PATH=/full/path/to/your/client_secret_file.json

**Example `.env` file:**

GOOGLE_ADS_DEVELOPER_TOKEN=ABCDEFG1234567890
GOOGLE_ADS_OAUTH_CONFIG_PATH=/Users/john/google-ads-mcp/client_secret_138737274875-abc123.apps.googleusercontent.com.json

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 · 584 lines

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

  1. # Google Ads MCP Server 🚀
  2. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  3. [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
  4. [![FastMCP](https://img.shields.io/badge/FastMCP-v2.8.0-green.svg)](https://github.com/jlowin/fastmcp)
  5. **A FastMCP-powered Model Context Protocol server for Google Ads API integration with automatic OAuth 2.0 authentication**
  6. Connect Google Ads API directly to Claude Desktop and other MCP clients with seamless OAuth 2.0 authentication, automatic token refresh, GAQL querying, and keyword research capabilities.
  7. <video controls width="1920" height="512" src="https://github.com/user-attachments/assets/1dc62f47-ace4-4dcf-8009-593ef7194b43">Your browser does not support the video tag.</video>
  8. ## Easy One-Click Setup
  9. For a simpler setup experience, we offer ready-to-use installers:
  10. 👉 **Download installer -** [https://gomarble.ai/mcp](https://gomarble.ai/mcp)
  11. ## Join our community for help and updates
  12. 👉 **Slack Community -** [AI in Ads](https://join.slack.com/t/ai-in-ads/shared_invite/zt-3f17k0kwl-kJskxR0FtcKJZhEYjc4X_A)
  13. ## Try Facebook ads mcp server also
  14. 👉 **Facebook Ads MCP -** [Facebook Ads MCP](https://github.com/gomarble-ai/facebook-ads-mcp-server)
  15. ## ✨ Features
  16. - 🔐 **Automatic OAuth 2.0** - One-time browser authentication with auto-refresh
  17. - 🔄 **Smart Token Management** - Handles expired tokens automatically
  18. - 📊 **GAQL Query Execution** - Run any Google Ads Query Language queries
  19. - 🏢 **Account Management** - List and manage Google Ads accounts
  20. - 🔍 **Keyword Research** - Generate keyword ideas with search volume data
  21. - 🚀 **FastMCP Framework** - Built on the modern MCP standard
  22. - 🖥️ **Claude Desktop Ready** - Direct integration with Claude Desktop
  23. - 🛡️ **Secure Local Storage** - Tokens stored locally, never exposed
  24. ## 📋 Available Tools
  25. | Tool | Description | Parameters | Example Usage |
  26. |------|-------------|------------|---------------|
  27. | `list_accounts` | List all accessible Google Ads accounts | None | "List all my Google Ads accounts" |
  28. | `run_gaql` | Execute GAQL queries with custom formatting | `customer_id`, `query`, `manager_id` (optional) | "Show me campaign performance for account 1234567890" |
  29. | `run_keyword_planner` | Generate keyword ideas with metrics | `customer_id`, `keywords`, `manager_id`, `page_url`, date range options | "Generate keyword ideas for 'digital marketing'" |
  30. **Note:** All tools automatically handle authentication - no token parameters required!
  31. ## 🚀 Quick Start
  32. ### Prerequisites
  33. Before setting up the MCP server, you'll need:
  34. - Python 3.10+ installed
  35. - A Google Cloud Platform account
  36. - A Google Ads account with API access
  37. ## 🔧 Step 1: Google Cloud Platform Setup
  38. ### 1.1 Create Google Cloud Project
  39. 1. **Go to [Google Cloud Console](https://console.cloud.google.com/)**
  40. 2. **Create a new project:**
  41. - Click "Select a project" → "New Project"
  42. - Enter project name (e.g., "Google Ads MCP")
  43. - Click "Create"
  44. ### 1.2 Enable Google Ads API
  45. 1. **In your Google Cloud Console:**
  46. - Go to "APIs & Services" → "Library"
  47. - Search for "Google Ads API"
  48. - Click on it and press "Enable"
  49. ### 1.3 Create OAuth 2.0 Credentials
  50. 1. **Go to "APIs & Services" → "Credentials"**
  51. 2. **Click "+ CREATE CREDENTIALS" → "OAuth 2.0 Client ID"**
  52. 3. **Configure consent screen (if first time):**
  53. - Click "Configure Consent Screen"
  54. - Choose "External" (unless you have Google Workspace)
  55. - Fill required fields:
  56. - App name: "Google Ads MCP"
  57. - User support email: Your email
  58. - Developer contact: Your email
  59. - Click "Save and Continue" through all steps
  60. 4. **Create OAuth Client:**
  61. - Application type: **"Desktop application"**
  62. - Name: "Google Ads MCP Client"
  63. - Click "Create"
  64. 5. **Download credentials:**
  65. - Click "Download JSON" button
  66. - Save file as `client_secret_[long-string].json` in your project directory
  67. ## 🔧 Step 2: Google Ads API Setup
  68. ### 2.1 Get Developer Token
  69. 1. **Sign in to [Google Ads](https://ads.google.com)**
  70. 2. **Go to Tools & Settings** (wrench icon in top navigation)
  71. 3. **Under "Setup", click "API Center"**
  72. 4. **Accept Terms of Service** if prompted
  73. 5. **Click "Apply for token"**
  74. 6. **Fill out application form:**
  75. - Describe your use case (e.g., "MCP integration for campaign analysis")
  76. - Provide technical details about your implementation
  77. 7. **Submit and wait for approval** (usually 1-3 business days)
  78. **Note:** You'll initially get a test token with limited functionality. After testing, you can apply for production access.
  79. ### 2.2 Find Your Developer Token
  80. Once approved:
  81. 1. **Return to API Center in Google Ads**
  82. 2. **Copy your Developer Token** (format: `XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX`)
  83. ## 🔧 Step 3: Installation & Setup
  84. ### 3.1 Clone and Install
  85. ```bash
  86. # Clone the repository
  87. git clone https://github.com/yourusername/google-ads-mcp-server.git
  88. cd google-ads-mcp-server
  89. # Create virtual environment (recommended)
  90. python3 -m venv .venv
  91. source .venv/bin/activate # On Windows: .venv\Scripts\activate
  92. # Install dependencies
  93. pip install -r requirements.txt
  94. ```
  95. ### 3.2 Environment Configuration
  96. Create a `.env` file in your project directory:
  97. ```bash
  98. # Copy the example file
  99. cp .env.example .env
  100. ```
  101. Edit `.env` with your credentials:
  102. ```bash
  103. # Required: Google Ads API Developer Token
  104. GOOGLE_ADS_DEVELOPER_TOKEN=your_developer_token_here
  105. # Required: Path to OAuth credentials JSON file (downloaded from Google Cloud)
  106. GOOGLE_ADS_OAUTH_CONFIG_PATH=/full/path/to/your/client_secret_file.json
  107. ```
  108. **Example `.env` file:**
  109. ```bash
  110. GOOGLE_ADS_DEVELOPER_TOKEN=ABCDEFG1234567890
  111. GOOGLE_ADS_OAUTH_CONFIG_PATH=/Users/john/google-ads-mcp/client_secret_138737274875-abc123.apps.googleusercontent.com.json
  112. ```
  113. ## 🖥️ Step 4: Claude Desktop Integration
  114. ### 4.1 Locate Claude Configuration
  115. Find your Claude Desktop configuration file:
  116. **macOS:**
  117. ```bash
  118. ~/Library/Application Support/Claude/claude_desktop_config.json
  119. ```
  120. **Windows:**
  121. ```bash
  122. %APPDATA%\Claude\claude_desktop_config.json
  123. ```
  124. ### 4.2 Add MCP Server Configuration
  125. Edit the configuration file and add your Google Ads MCP server:
  126. ```json
  127. {
  128. "mcpServers": {
  129. "google-ads": {
  130. "command": "/full/path/to/your/project/.venv/bin/python",
  131. "args": [
  132. "/full/path/to/your/project/server.py"
  133. ]
  134. }
  135. }
  136. }
  137. ```
  138. **Real Example:**
  139. ```json
  140. {
  141. "mcpServers": {
  142. "google-ads": {
  143. "command": "/Users/marble-dev-01/workspace/google_ads_with_fastmcp/.venv/bin/python",
  144. "args": [
  145. "/Users/marble-dev-01/workspace/google_ads_with_fastmcp/server.py"
  146. ]
  147. }
  148. }
  149. }
  150. ```
  151. **Important:**
  152. - Use **absolute paths** for all file locations
  153. - On Windows, use forward slashes `/` or double backslashes `\\` in paths
  154. - Replace `your_developer_token_here` with your actual developer token
  155. ### 4.3 Restart Claude Desktop
  156. Close and restart Claude Desktop to load the new configuration.
  157. ## 🔐 Step 5: First-Time Authentication
  158. ### 5.1 Trigger OAuth Flow
  159. 1. **Open Claude Desktop**
  160. 2. **Try any Google Ads command**, for example:
  161. ```
  162. "List all my Google Ads accounts"
  163. ```
  164. ### 5.2 Complete Authentication
  165. 1. **Browser opens automatically** to Google OAuth page
  166. 2. **Sign in** with your Google account (the one with Google Ads access)
  167. 3. **Grant permissions** by clicking "Allow"
  168. 4. **Browser shows success page**
  169. 5. **Return to Claude** - your command will complete automatically!
  170. ### 5.3 Verify Setup
  171. After authentication, you should see:
  172. - A `google_ads_token.json` file created in your project directory
  173. - Your Google Ads accounts listed in Claude's response
  174. ## 📖 Usage Examples
  175. ### Basic Account Operations
  176. ```
  177. "List all my Google Ads accounts"
  178. "Show me the account details and which ones have active campaigns"
  179. ```
  180. ### Campaign Analysis
  181. ```
  182. "Show me campaign performance for account 1234567890 in the last 30 days"
  183. "Get conversion data for all campaigns in the last week"
  184. "Which campaigns have the highest cost per conversion?"
  185. ```
  186. ### Keyword Research
  187. ```
  188. "Generate keyword ideas for 'digital marketing' using account 1234567890"
  189. "Find keyword opportunities for 'AI automation' with search volume data"
  190. "Research keywords for the page https://example.com/services"
  191. ```
  192. ### Custom GAQL Queries
  193. ```
  194. "Run this GAQL query for account 1234567890:
  195. SELECT campaign.name, metrics.clicks, metrics.cost_micros
  196. FROM campaign
  197. WHERE segments.date DURING LAST_7_DAYS"
  198. "Get keyword performance data:
  199. SELECT ad_group_criterion.keyword.text, metrics.ctr, metrics.average_cpc
  200. FROM keyword_view
  201. WHERE metrics.impressions > 100"
  202. ```
  203. ## 🔍 Advanced GAQL Examples
  204. ### Campaign Performance with Revenue
  205. ```sql
  206. SELECT
  207. campaign.id,
  208. campaign.name,
  209. metrics.clicks,
  210. metrics.impressions,
  211. metrics.cost_micros,
  212. metrics.conversions,
  213. metrics.conversions_value
  214. FROM campaign
  215. WHERE segments.date DURING LAST_30_DAYS
  216. ORDER BY metrics.cost_micros DESC
  217. ```
  218. ### Keyword Performance Analysis
  219. ```sql
  220. SELECT
  221. campaign.name,
  222. ad_group_criterion.keyword.text,
  223. ad_group_criterion.keyword.match_type,
  224. metrics.ctr,
  225. metrics.average_cpc,
  226. metrics.quality_score
  227. FROM keyword_view
  228. WHERE segments.date DURING LAST_7_DAYS
  229. AND metrics.impressions > 100
  230. ORDER BY metrics.conversions DESC
  231. ```
  232. ### Device Performance Breakdown
  233. ```sql
  234. SELECT
  235. campaign.name,
  236. segments.device,
  237. metrics.clicks,
  238. metrics.cost_micros,
  239. metrics.conversions
  240. FROM campaign
  241. WHERE segments.date DURING LAST_30_DAYS
  242. AND campaign.status = 'ENABLED'
  243. ```
  244. ## 📁 Project Structure
  245. ```
  246. google-ads-mcp-server/
  247. ├── server.py # Main MCP server
  248. ├── oauth/
  249. │ ├── __init__.py # Package initialization
  250. │ └── google_auth.py # OAuth authentication logic
  251. ├── google_ads_token.json # Auto-generated token storage (gitignored)
  252. ├── client_secret_[long-string].json # Your OAuth credentials (gitignored)
  253. ├── .env # Environment variables (gitignored)
  254. ├── .env.example # Environment template
  255. ├── .gitignore # Git ignore file
  256. ├── requirements.txt # Python dependencies
  257. ├── LICENSE # MIT License
  258. └── README.md # This file
  259. ```
  260. ## 🔒 Security & Best Practices
  261. ### File Security
  262. - ✅ **Credential files are gitignored** - Never committed to version control
  263. - ✅ **Local token storage** - Tokens stored in `google_ads_token.json` locally
  264. - ✅ **Environment variables** - Sensitive data in `.env` file
  265. - ✅ **Automatic refresh** - Minimal token exposure time
  266. ### Recommended File Permissions
  267. ```bash
  268. # Set secure permissions for sensitive files
  269. chmod 600 .env
  270. chmod 600 google_ads_token.json
  271. chmod 600 client_secret_*.json
  272. ```
  273. ### Production Considerations
  274. 1. **Use environment variables** instead of `.env` files in production
  275. 2. **Implement rate limiting** to respect API quotas
  276. 3. **Monitor API usage** in Google Cloud Console
  277. 4. **Secure token storage** with proper access controls
  278. 5. **Regular token rotation** for enhanced security
  279. ## 🛠️ Troubleshooting
  280. ### Authentication Issues
  281. | Issue | Symptoms | Solution |
  282. |-------|----------|----------|
  283. | **No tokens found** | "Starting OAuth flow" message | ✅ Normal for first-time setup - complete browser authentication |
  284. | **Token refresh failed** | "Refreshing token failed" error | ✅ Delete `google_ads_token.json` and re-authenticate |
  285. | **OAuth flow failed** | Browser error or no response | Check credentials file path and internet connection |
  286. | **Permission denied** | "Access denied" in browser | Ensure Google account has Google Ads access |
  287. ### Configuration Issues
  288. | Issue | Symptoms | Solution |
  289. |-------|----------|----------|
  290. | **Environment variables missing** | "Environment variable not set" | Check `.env` file and Claude config `env` section |
  291. | **File not found** | "FileNotFoundError" | Verify absolute paths in configuration |
  292. | **Module import errors** | "ModuleNotFoundError" | Run `pip install -r requirements.txt` |
  293. | **Python path issues** | "Command not found" | Use absolute path to Python executable |
  294. ### Claude Desktop Issues
  295. | Issue | Symptoms | Solution |
  296. |-------|----------|----------|
  297. | **Server not connecting** | No Google Ads tools available | Restart Claude Desktop, check config file syntax |
  298. | **Invalid JSON config** | Claude startup errors | Validate JSON syntax in config file |
  299. | **Permission errors** | "Permission denied" on startup | Check file permissions and paths |
  300. ### API Issues
  301. | Issue | Symptoms | Solution |
  302. |-------|----------|----------|
  303. | **Invalid customer ID** | "Customer not found" | Use 10-digit format without dashes: `1234567890` |
  304. | **API quota exceeded** | "Quota exceeded" error | Wait for quota reset or request increase |
  305. | **Invalid developer token** | "Authentication failed" | Verify token in Google Ads API Center |
  306. | **GAQL syntax errors** | "Invalid query" | Check GAQL syntax and field names |
  307. ### Debug Mode
  308. Enable detailed logging for troubleshooting:
  309. ```python
  310. # Add to server.py for debugging
  311. import logging
  312. logging.basicConfig(level=logging.DEBUG)
  313. ```
  314. ### Getting Help
  315. If you encounter issues:
  316. 1. **Check the error message carefully** - it usually indicates the exact problem
  317. 2. **Verify all file paths** are absolute and correct
  318. 3. **Ensure environment variables** are properly set
  319. 4. **Check Google Cloud Console** for API quotas and billing
  320. 5. **Restart Claude Desktop** after any configuration changes
  321. ## 🚀 Advanced Configuration
  322. ### HTTP Transport Mode
  323. For web deployment or remote access:
  324. ```bash
  325. # Start server in HTTP mode
  326. python3 server.py --http
  327. ```
  328. **Claude Desktop config for HTTP:**
  329. ```json
  330. {
  331. "mcpServers": {
  332. "google-ads": {
  333. "url": "http://127.0.0.1:8000/mcp"
  334. }
  335. }
  336. }
  337. ```
  338. ### Custom Token Storage
  339. Modify token storage location in `oauth/google_auth.py`:
  340. ```python
  341. # Custom token file location
  342. def get_token_path():
  343. return "/custom/secure/path/google_ads_token.json"
  344. ```
  345. ### Manager Account Configuration
  346. For managing multiple accounts under an MCC:
  347. ```bash
  348. # Add to .env file
  349. GOOGLE_ADS_LOGIN_CUSTOMER_ID=123-456-7890
  350. ```
  351. ## 🤝 Contributing
  352. We welcome contributions! Here's how to get started:
  353. ### Development Setup
  354. ```bash
  355. # Fork and clone the repository
  356. git clone https://github.com/yourusername/google-ads-mcp-server.git
  357. cd google-ads-mcp-server
  358. # Create development environment
  359. python3 -m venv .venv
  360. source .venv/bin/activate
  361. # Install dependencies
  362. pip install -r requirements.txt
  363. # Set up development environment
  364. cp .env.example .env
  365. # Add your development credentials to .env
  366. ```
  367. ### Making Changes
  368. 1. **Create a feature branch:** `git checkout -b feature/amazing-feature`
  369. 2. **Make your changes** with appropriate tests
  370. 3. **Test thoroughly** with different account configurations
  371. 4. **Update documentation** as needed
  372. 5. **Commit changes:** `git commit -m 'Add amazing feature'`
  373. 6. **Push to branch:** `git push origin feature/amazing-feature`
  374. 7. **Open a Pull Request** with detailed description
  375. ### Testing Your Changes
  376. ```bash
  377. # Test authentication flow
  378. python3 server.py --test-auth
  379. # Test API connectivity
  380. python3 -c "
  381. from oauth.google_auth import get_oauth_credentials
  382. creds = get_oauth_credentials()
  383. print('✅ Authentication successful!')
  384. "
  385. # Test with Claude Desktop
  386. # Add your server to Claude config and test various commands
  387. ```
  388. ## 📊 API Limits and Quotas
  389. ### Google Ads API Quotas
  390. - **Basic access:** 15,000 operations per day
  391. - **Standard access:** 40,000 operations per day
  392. - **Request rate:** 1,600 requests per minute per developer token
  393. ### Best Practices for API Usage
  394. 1. **Cache results** when possible to reduce API calls
  395. 2. **Use date ranges** to limit data volume
  396. 3. **Batch requests** when supported
  397. 4. **Monitor usage** in Google Cloud Console
  398. 5. **Implement retry logic** for rate limit errors
  399. ### Quota Management
  400. ```bash
  401. # Monitor usage in Google Cloud Console
  402. # Go to APIs & Services → Quotas
  403. # Search for "Google Ads API" to see current usage
  404. ```
  405. ## 📄 License
  406. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
  407. ---
  408. ### MIT License
  409. ```
  410. Copyright (c) 2025 Google Ads MCP Server Contributors
  411. Permission is hereby granted, free of charge, to any person obtaining a copy
  412. of this software and associated documentation files (the "Software"), to deal
  413. in the Software without restriction, including without limitation the rights
  414. to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  415. copies of the Software, and to permit persons to whom the Software is
  416. furnished to do so, subject to the following conditions:
  417. The above copyright notice and this permission notice shall be included in all
  418. copies or substantial portions of the Software.
  419. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  420. IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  421. FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  422. AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  423. LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  424. OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  425. SOFTWARE.
  426. ```
  427. ## 📈 Roadmap
  428. ### Upcoming Features
  429. - 🔄 **Enhanced keyword research** with competitor analysis
  430. - 📊 **Built-in data visualization** with charts and graphs
  431. - 🤖 **AI-powered optimization suggestions**
  432. - 📝 **Campaign creation and management tools**
  433. - 🔍 **Advanced reporting capabilities**
  434. - 🌐 **Multi-language support**
  435. ---
  436. **Made with ❤️ for the MCP community**
  437. *Connect your Google Ads data directly to AI assistants and unlock powerful advertising insights through natural language conversations.*

Ratings and comments

Sign in to rate this skill.

Sign in

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