Google Ads API v20 MCP Server

How to use

Start the MCP server and connect with your preferred MCP client to issue commands like listing accounts, creating campaigns, managing ad groups, and running GAQL queries. You can perform typical Google Ads operations using natural-language style calls such as listing accounts, creating campaigns, fetching performance data, and adding keywords or negatives for Performance Max campaigns. The server also supports advanced tasks like generating reports, handling change history, and running experiments.

How to install

Prerequisites: you need Python 3.8+ and pip installed on your system.

Install the MCP package and dependencies. Run these commands in your shell.

pip install -e .

# Or install dependencies directly
pip install mcp google-ads pydantic httpx tenacity python-dotenv beautifulsoup4 structlog

Additional configuration and usage notes

Environment variables for authentication and API access are required. You can configure them in a .env file or in a config file located at ~/.config/google-ads-mcp/config.json. The following environment variables are used by the MCP server.

Create a .env file with your credentials, or set them in your environment before starting the server.

MCP configuration

{
  "mcpServers": {
    "google-ads": {
      "command": "python",
      "args": ["-m", "google-ads-mcp"],
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "your_token",
        "GOOGLE_ADS_CLIENT_ID": "your_client_id",
        "GOOGLE_ADS_CLIENT_SECRET": "your_secret",
        "GOOGLE_ADS_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}

Usage examples

Basic operations like listing accounts or creating a campaign can be invoked through your MCP client by referencing the corresponding tools exposed by the server. For example, you can request to list accounts, create a campaign with a specific customer_id and name, or fetch campaign performance for a given date range.

Security notes

Never commit credentials to version control. Prefer service accounts for production, enable 2FA on Google Ads accounts, rotate refresh tokens regularly, and monitor API usage with alerts.

API features and tools

This server exposes a broad set of Google Ads operations, including account management, campaign and ad group CRUD, ad creation, asset management, budgeting, keyword handling (including Performance Max level negatives), reporting with GAQL, and advanced features like recommendations, change history, and experiments.

list_accounts

List accounts available to the authenticated user, including basic account info and hierarchy when applicable.

create_campaign

Create a new campaign with parameters such as customer_id, name, budget, and type, leveraging v20 features.

get_campaign_performance

Retrieve performance data for a specified campaign over a date range using GAQL or built-in reporting features.

run_gaql_query

Execute a custom GAQL query to fetch campaign, ad, or performance data with flexible filtering and sorting.

add_negative_keywords

Add negative keywords to a campaign or to a Performance Max campaign to refine targeting.