PerfoAds MCP

A self-hosted MCP server that works with Google Ads. It lets an AI assistant (Claude Desktop, Claude Code, Cursor and other MCP apps) read your Google Ads accounts, run 168 deterministic account checks, and change things only with your approval and within limits you set in a policy file.

PerfoAds MCP works with Google Ads. It is not made, endorsed or supported by Google (not a Google product). It works with the Google Ads API through your own Google Cloud project and your own sign-in; nothing goes through anyone else's servers.

Package and CLI: perfoads-mcp. License: Apache-2.0. Status: early alpha. On npm: perfoads-mcp (0.2.0-alpha.2).

Work with Paweł

The checks say what is wrong: the evidence, how serious it is and the real spend behind it. They do not say how to fix it. Want fixes, not just findings? PerfoAds adds fix plans; Paweł Wilk offers a free 1-hour call - perfoads.com

The safety promise

No change can be applied through MCP without a human approving it outside the model. On hosts where the agent also has a shell or controls the browser (Claude Code, Cursor, browser-control tools) this holds only with the hardened setup (server + store under a separate OS user or in a container, approval_mode: code_only and open_browser: false), and only if you do the human steps (your password, approving, policy edits) from a session the AI can't change: another account's login session, SSH from another device, or with the AI agent sandboxed. An AI with a shell on your user can change your shell startup files, fake sudo and capture what you type.

The one exception is one you make yourself: the auto tier in your policy file (off unless you set it, and only for pausing a campaign or lowering a budget).

What this means in practice:

• Changes are off until your policy file lists an account under accounts.write.
• Google checks the change first without applying it (validate only). Then it is shown to you on a local approval page with the account name, id and currency first, the exact change, every campaign it reaches, and the AI's reason in a separate "unverified" box.
• You approve with the 6-character code from that page (typed into your AI app's form or a terminal), or a click on the page in apps without forms. An AI saying "yes" approves nothing.
• The server applies the change once, reads it back from Google, and logs every step in a hash-chained audit log. Most changes can be undone within 30 days (as a new approved change); see the per-type table.

Read docs/THREAT-MODEL.md for what this protects against and what it does not.

Requirements

• Node.js 22.13 or later (it uses the built-in node:sqlite).
• Your own Google Cloud project with the Google Ads API enabled.
• An OAuth client of type "Desktop app" in that project.
• Explorer access to the Google Ads API, applied for in Google Cloud Console for that project. Until it is approved, only Google Ads test accounts work. No developer token is needed.

Step by step: docs/SETUP.md.

Install and connect

npx perfoads-mcp@0.2.0-alpha.2 init

Always name the exact version (@0.2.0-alpha.2, not @latest or none), so npm can't hand you a different release. init asks for your OAuth client id and secret, opens Google's sign-in in your browser, saves the sign-in encrypted, writes a read-only starter policy, runs doctor, and prints the config for your AI app.

Or build from source:

git clone https://github.com/vilovibe/perfoads-mcp.git
cd perfoads-mcp
pnpm install --frozen-lockfile && pnpm build
node packages/cli/bin/perfoads-mcp.js init

init then prints your AI app's config for that copy (full path to node and to `packag

... View full README on GitHub