Google Ads

The Google Ads MCP Server provides a secure, extensible bridge between Google Ads data and AI assistants using the Model Context Protocol. With this server, you can analyze campaigns, optimize bidding, and manage ads through natural language conversations, without writing custom API code for every task.

How to use

You interact with the server through an MCP client (such as Claude Desktop). Start by initializing the connection with your Google Ads credentials, then issue natural language requests that map to specific MCP tools. For example, you can ask for account lists, campaign performance, keyword quality scores, or to adjust campaign budgets. The MCP layer translates your natural language commands into Google Ads API actions and returns structured results in your preferred format.

Typical workflows include: listing all accessible Google Ads accounts, analyzing campaign performance over a date range, retrieving keyword metrics, discovering high-potential search terms, and updating budgets or campaign statuses. The system supports a mix of read-only analyses and write actions, enabling you to perform end-to-end campaign management through conversation.

How to install

# Prerequisites
- Python 3.8 or higher
- Google Ads account with active campaigns
- Google Ads API Developer Token

# 1) Clone the project
git clone https://github.com/johnoconnor0/google-ads-mcp.git
cd google-ads-mcp

# 2) Install Python dependencies
pip install -r requirements.txt

# 3) Generate OAuth credentials refresh token
python generate_refresh_token.py

# 4) Prepare MCP server invocation (example for Claude Desktop)
# You will run the MCP server locally and point Claude to it.
# The server is invoked with Python and the path to the main script.

5. Configure Claude Desktop to connect to the MCP server by specifying the executable and script path, for example: create an entry under your MCP servers with the command set to python and the argument to the absolute path of your Google Ads MCP script. Restart Claude Desktop to apply the changes.

Configuration

Authentication and connectivity are configured via environment variables and a YAML/JSON configuration file. The server uses OAuth 2.0 credentials to access Google Ads and can optionally cache data for performance.

# Environment variables
export GOOGLE_ADS_DEVELOPER_TOKEN="YOUR_DEVELOPER_TOKEN"
export GOOGLE_ADS_CLIENT_ID="YOUR_CLIENT_ID"
export GOOGLE_ADS_CLIENT_SECRET="YOUR_CLIENT_SECRET"
export GOOGLE_ADS_REFRESH_TOKEN="YOUR_REFRESH_TOKEN"
export GOOGLE_ADS_LOGIN_CUSTOMER_ID="YOUR_MCC_ID"  # optional

# Optional caching and logging
export GOOGLE_MCP_CACHE_BACKEND="memory"  # or redis
export GOOGLE_MCP_LOG_LEVEL="INFO"

Example runtime invocation for Claude integration is shown as part of the Quick Start snippet, where the MCP server runs a Python script and Claude points at that script to handle requests.

Troubleshooting

Common issues usually involve credentials, token lifetimes, or misformatted customer IDs. Ensure you are using a valid 10-digit customer ID (no hyphens) and that your developer token is approved for production access. If you encounter authentication failures, regenerate your refresh token and verify the client ID and client secret.

If you see rate limits, reduce the date range or request size, enable caching, and consider throttling requests. For debugging, enable debug logging and inspect the log file for detailed error messages.

Available tools

google_ads_initialize

Initialize API connection with OAuth credentials.

google_ads_list_accounts

List all accessible Google Ads accounts.

google_ads_campaign_performance

Get comprehensive campaign metrics with filtering and date ranges.

google_ads_keyword_performance

Analyze keyword-level performance including quality scores and positions.

google_ads_search_terms

Retrieve actual search queries triggering ads.

google_ads_ad_group_performance

Analyze ad group level metrics.

google_ads_recommendations

Fetch Google's optimization recommendations.

google_ads_update_campaign_budget

Modify campaign daily budget.

google_ads_update_campaign_status

Pause or enable campaigns.

google_ads_custom_query

Execute custom GAQL queries.