Google Ads API — how we use it.

1. Company & business model

Pravatti s.r.o. operates under the Virtualien brand — a full-service performance marketing agency based in Slovakia. Our work spans paid search, paid social, analytics and CRO for clients across the EU.

We manage Google Ads campaigns on behalf of contracted clients who grant us access to their accounts through our Manager (MCC) account, ID 638-048-0172. We do not sell, license, redistribute or otherwise provide the tool to any third party; it is used exclusively by our internal team to manage the client accounts we are contractually authorised to operate. We do not advertise for third-party agencies, and we do not operate a SaaS product on top of the Google Ads API.

2. Who uses the tool

The tool is used internally by our agency team — primarily by the lead PPC specialist, with read-only visibility for other Virtualien team members and, where relevant, for the end clients (who see outputs as exported reports). Clients do not have direct access to the tool itself.

The tool is installed locally on team-member workstations; there is no hosted or externally accessible interface. No registration, login page or external entry point to the tool is exposed on the internet.

3. Typical daily usage

• Pulling campaign, ad-group, keyword and search-term performance reports for internal review and client-facing reporting.
• Reviewing Google Ads recommendations and auction / change-history insights before manual optimisation.
• Making routine campaign-management edits — daily budget updates, pausing or enabling campaigns, adjusting ad status — in response to performance analysis.
• Generating client-ready PDF / spreadsheet reports, delivered to clients as attachments. Clients do not log in to the tool.

4. Tool design

The tool is a local AI-assisted workflow built on top of Claude Code (Anthropic's command-line coding assistant) using the open Model Context Protocol (MCP). Two custom MCP servers wrap the official Google Ads Python SDK and expose a controlled set of operations to the assistant:

• A read-only reporting server (based on Google's reference implementation google_ads_mcp), used for safe analytical queries.
• A management server (community implementation johnoconnor0/google-ads-mcp) used for the campaign-management mutations listed below.

Authentication uses OAuth 2.0 with a refresh token tied to the Virtualien MCC (638-048-0172). Each team-member workstation holds its own credentials locally.

No API data is stored on external servers, no API data is shared with third parties, and no data flows through any hosted SaaS backend. A lightweight local cache is used only to respect Google Ads API rate limits; it is not a persistent analytics database and is not exposed to clients.

All destructive operations (budget updates, pause / enable, ad-status changes) require an explicit human-in-the-loop confirmation in the Claude Code session before they are sent to the API; the assistant cannot execute mutations autonomously.

5. Google Ads API services called

The tool calls the following Google Ads API services / resources via the official google-ads-python SDK (API v20+):

• CustomerService / customer resource — list accessible customers under the MCC, read account-level metadata.
• GoogleAdsService (search / searchStream) — run GAQL queries for campaign, ad-group, ad, keyword, search-term, geo and device performance reports.
• CampaignService — update campaign status (ENABLED / PAUSED) for campaigns we manage.
• CampaignBudgetService — update daily budgets (amount_micros) on campaigns we manage.
• AdGroupService and AdGroupAdService — review ad-group and ad status; pause / enable individual ads.
• RecommendationService — read Google's optimisation recommendations for review before manual action.

Additional read-only services (e.g. KeywordPlanService) may be consulted on a per-case basis; the list above covers all recurring usage.

6. Data handling & commitments

• Data from the Google Ads API is used solely to manage the campaigns of the client whose account the data belongs to.
• We do not sell, license or redistribute Google Ads API data.
• We do not use Google Ads API data to train any generative AI or machine-learning models.
• We do not combine data across clients for cross-client benchmarking or any derivative product.
• Access is scoped via OAuth and limited to accounts linked under our MCC.
• Full privacy policy: virtualien.space/privacy.

Our use of information received from Google APIs adheres to the Google API Services User Data Policy, including the Limited Use requirements.

7. Interface — terminal mock-up

The tool has no graphical interface. All interactions happen inside the Claude Code terminal on an authorised workstation. A representative session looks like this:

8. Contact

Questions about the tool or this documentation: jakub@pravatti.sk.