google-ads

This MCP server exposes Google Ads data to Claude Desktop through a Python-based MCP server. It provides tools for managing ad groups, keywords, and budgets, with built-in visualizations and caching to improve responsiveness. The server supports multiple environments (development, testing, production) and can be run directly or via Docker as part of a larger deployment. To start using it with Claude Desktop, configure Claude to point at the server and enable the available tools to query campaigns, accounts, performance metrics, budgets, and more. You can leverage the supplied tools to fetch ad group details, analyze keyword performance, and visualize budget utilization within Claude.

Available tool families include Ad Group Management, Keyword Management, and Budget Management. Each family exposes a set of MCP functions such as get_ad_groups, get_ad_groups_json, create_ad_group, get_keywords, analyze_search_terms, get_budgets, and update_budget, among others. The CLI-like and JSON endpoints underpin rich visualizations inside Claude Desktop, including performance charts, word clouds, and tabular dashboards. The server also supports artifacts integration for data visualization and caching to minimize repeated API calls to Google Ads.

Prerequisites

• Python 3.9 or higher
• Claude Desktop installed
• Google Ads API credentials (with appropriate access)
• Docker (optional, for containerized deployment)

Local installation (development)

1. Clone the repository:

   git clone https://github.com/yourusername/google-ads-mcp.git
   cd google-ads-mcp
   

2. Create and activate a virtual environment:

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Create a .env file with your credentials:

   cp .env.example .env
   # Edit .env with your Google Ads credentials
   

5. Run the server locally:

   python server.py
   

Docker deployment

1. Build the Docker image:

   docker build -t google-ads-mcp:latest .
   

2. Run the container (with env file):

   docker run -p 8000:8000 --env-file .env google-ads-mcp:latest
   

Alternatively, use docker-compose if provided in the repo:

docker-compose up -d

Configuration for Claude Desktop integration

• Ensure Claude Desktop is configured to connect to the MCP server using the Python path to server.py, as shown in the Claude Desktop Integration section of the README.
• Update .env with Google Ads credentials and any environment-specific settings (APP_ENV, feature flags).

Tips and common issues:

• Ensure Google Ads API credentials have the necessary permissions for the campaigns, accounts, and metrics you plan to query.
• If you see authentication errors, verify that the path in GOOGLE_ADS_CREDENTIALS points to a valid credentials JSON file and that the environment has access to Google Ads API.
• When using Claude Desktop, restart the app after adding or changing the mcpServers configuration to ensure tools appear.
• Use the get_budgets and get_budgets_json tools to verify budget data is flowing correctly and visualize utilization in Claude.
• If running in Docker, map the environment file correctly and ensure the container has access to any required secrets or credentials.
• Check environment-specific configurations (APP_ENV) to avoid unintended data access between dev/test/prod.