Google Ads MCP — Internal Reporting Prototype

A private, read-only MCP integration prototype for retrieving and analyzing Google Ads reporting data from authorized accounts.

Status: Development prototype. Not intended for public SaaS usage.

This project is under active development. The read-only tool interfaces and documentation are complete, but the live Google Ads API calls have not yet been fully tested end-to-end against a production developer token. Parts of the client are intentionally marked with TODO until they are verified.

---

What this is

Google Ads MCP is a small tool that connects Claude Code (or any MCP-compatible client) to the Google Ads API through a locally operated Model Context Protocol server. It exposes a handful of read-only reporting functions so that an authorized developer can pull campaign, ad group, keyword, search-term, cost and conversion data into an analysis workflow.

It is a personal / internal developer tool. It is not a public product, it is not offered as a SaaS, and it does not resell or redistribute Google Ads data.

Features

• List accessible Google Ads accounts
• List client accounts connected to a manager account (MCC)
• Retrieve campaign performance
• Retrieve ad group performance
• Retrieve keyword performance
• Retrieve search terms
• Retrieve conversion metrics
• Retrieve daily spend
• Return structured JSON for analysis in Claude Code

Limitations (by design)

This tool is deliberately constrained. It is read-only and cannot change anything in a Google Ads account:

• Read-only — no write / mutate operations of any kind
• No campaign creation
• No budget changes
• No bid changes
• No pausing or deleting campaigns
• No access to accounts without explicit authorization
• No public user access

Architecture

Claude Code
  → local MCP server
    → official Google Ads Python client
      → Google Ads API
        → authorized Google Ads manager and client accounts

All components run locally on the developer's machine. Credentials never leave the local environment, and no intermediate server is involved. See docs/ARCHITECTURE.md for details.

Installation

Requires Python 3.12+.

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env

Then edit .env and fill in your own credentials (see below).

Environment variables

Copy .env.example to .env and provide your own values:

GOOGLE_ADS_DEVELOPER_TOKEN=
GOOGLE_ADS_CLIENT_ID=
GOOGLE_ADS_CLIENT_SECRET=
GOOGLE_ADS_REFRESH_TOKEN=
GOOGLE_ADS_LOGIN_CUSTOMER_ID=

⚠️ Never commit real credentials. Store secrets only in a local .env file or a secure secret manager. The provided .gitignore already excludes .env and common credential files.

Running the MCP server

python -m google_ads_mcp.server

Note: the server registers the read-only tools and validates configuration on startup. Live Google Ads queries require a valid developer token and OAuth refresh token and have not yet been fully validated — see the project status note above.

Running tests

pip install -r requirements.txt
pytest

The current test suite covers configuration loading and customer-ID normalization / validation. It does not make live API calls.

Google Ads API compliance

• Only Google Ads accounts for which the authenticated user has explicit authorization are accessed.
• Data is used solely for internal reporting, auditing and optimization analysis.
• Credentials are never logged.
• Data is not sold or redistributed.
• The tool is not offered to the general public.

See docs/SECURITY.md, docs/PRIVACY.md and docs/GOOGLE_ADS_API_TOOL_DESIGN.md for the full policy and design documentation.

Documentation

Document	Purpose
docs/GOOGLE_ADS_API_TOOL_DESIGN.md	Full tool design document for the Google Ads API application
docs/ARCHITECTURE.md	Technical architecture and data flow
docs/SECURITY.md	Security controls and procedures
docs/PRIVACY.md	Privacy policy for handled data
docs/BASIC_ACCESS_APPLICATION.md	Prepared answers for the Basic Access application form

License

MIT