Google Ads MCP Server 🚀

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