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:

Area	Status
Google Ads API version	v20
Implemented services	90 / 103
Coverage model	1:1 service mapping where implemented
Type policy	Generated Google Ads protobuf types
Feature parity	docs/FEATURE_PARITY.md
Detailed audit	TRACKER.md

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:

Group	Includes
core	Customers, campaigns, budgets, ad groups, keywords, ads, conversions, GAQL
assets	Assets, asset groups, asset sets, campaign/ad group/customer assets
targeting	Criteria, geo targets, audiences, custom interests, user lists
bidding	Strategies, bid modifiers, data exclusions, seasonality adjustments
planning	Keyword plans, reach planning, brand suggestions
reporting	Search, fields, recommendations, invoices, audience insights
conversion	Uploads, adjustments, value rules, goals, user data, remarketing
organization	Labels, shared sets, shared criteria
customizers	Customizer attributes, campaign/ad group/customer customizers, ad parameters
account	Access, manager links, billing, payments, identity, product/data links
other	Smart campaigns, batch jobs, user data

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

Project	Description
OpenPromo	AI-native workspace for creating, publishing, and managing ads
@promobase/ad-platforms	TypeScript ad platform SDK with AI SDK tools for Meta, TikTok, and Google Ads work
promobase/ad-platform-sdks	Source repo for Promobase's multi-platform ad SDKs

License

MIT © Promobase

Disclaimer

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