google-ads-mcp

A typed MCP server for letting AI agents operate Google Ads.

Built by Promobase for OpenPromo, the AI-native workspace for creating, publishing, and managing ads.

What

google-ads-mcp wraps the official Google Ads Python SDK in a Model Context Protocol server. It exposes Google Ads API v20 services as typed MCP tools, so LLMs and agent runtimes can safely inspect accounts, create campaigns, manage budgets, upload conversions, work with assets, and run GAQL search.

This repo is the Google Ads execution layer behind OpenPromo's agent workflows. For application-facing, multi-platform ad publishing and inbox automation, use the companion SDK:

@promobase/ad-platforms - one TypeScript SDK for Meta, TikTok, and soon Google Ads, with AI SDK tools and production clients for ad platform automation.

Why

Google Ads has a large, typed API surface, but it is hard for agents to use directly. This server keeps the reliability of the official Python SDK while giving agents a structured tool interface:

• Official SDK foundation - built on google-ads, including its auth, retries, paging, and protobuf types.

• Typed service wrappers - implementations use Google Ads API v20 generated service, resource, enum, and operation types.

• Agent-ready MCP tools - FastMCP servers grouped by workflow: core, assets, targeting, bidding, planning, reporting, conversions, account management, and more.

• GAQL access - search and metadata tools for reporting, discovery, and account inspection.

• Production-oriented scope - designed for OpenPromo's ads loop: generate creative, build campaigns, publish, measure, and iterate.

Coverage

Current tracker status:

Core campaign, ad group, ad, budget, keyword, conversion, asset, audience, recommendation, account, billing, and reporting workflows are implemented. The scannable parity table lives in docs/FEATURE_PARITY.md; detailed implementation notes live in TRACKER.md.

Install

git clone https://github.com/promobase/google-ads-mcp.git
cd google-ads-mcp
uv sync

Create a .env file or export the required Google Ads credentials:

GOOGLE_ADS_DEVELOPER_TOKEN="your_developer_token"
GOOGLE_ADS_CLIENT_ID="your_client_id"
GOOGLE_ADS_CLIENT_SECRET="your_client_secret"
GOOGLE_ADS_REFRESH_TOKEN="your_refresh_token"
GOOGLE_ADS_LOGIN_CUSTOMER_ID="optional_manager_customer_id"

See .env.example for the full credential template.

Run

Run the default core tool group:

uv run main.py

Run every registered service group:

uv run main.py --groups all

Run a focused subset:

uv run main.py --groups core,assets,targeting,conversion

Available groups:

MCP Client

Example stdio configuration:

{
  "mcpServers": {
    "google-ads": {
      "command": "uv",
      "args": ["run", "main.py", "--groups", "all"],
      "cwd": "/path/to/google-ads-mcp",
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "...",
        "GOOGLE_ADS_CLIENT_ID": "...",
        "GOOGLE_ADS_CLIENT_SECRET": "...",
        "GOOGLE_ADS_REFRESH_TOKEN": "..."
      }
    }
  }
}

Use narrower groups for production agents when you want to reduce tool count and keep routing focused.

Development

# Format
uv run ruff format .

# Type check
uv run pyright

# Test
uv run pytest

When adding a service:

1. Check the Google Ads API v20 generated service types.

2. Implement the service wrapper with generated protobuf request, operation, resource, and enum types.

3. Register lightweight MCP tools for the service.

4. Add focused tests.

5. Update TRACKER.md.

6. Run uv run ruff format . and uv run pyright.

Related

License

MIT © Promobase

Disclaimer

This is an unofficial Google Ads API integration. It is not affiliated with, endorsed by, or supported by Google.