PerfoAds MCP: a free Google Ads MCP server

Key facts

Price

Free

License

Apache-2.0, open source

Runs on

Your own computer (Mac, Windows or Linux) with Node.js 22.13 or later

Works in

Claude Desktop, Claude Code, the ChatGPT desktop app, Codex and Cursor

Doesn't work in

ChatGPT on the web

Tools

25

Checks

162, with no AI involved

Changes

14 kinds, each with an undo

Who approves

You, on a page outside the chat

Built by

PerfoAds (Pawel Wilk)

Status

Early release

What is a Google Ads MCP server?

What can PerfoAds MCP do?

Read your accounts

14 read tools cover campaigns, ad groups, keywords, search terms, budgets and bidding, negative keywords, ads and assets, audiences, conversions and change history. Negative keywords are words you've told Google never to show your ads for. Accounts under a manager account show up too. Money comes back in each account's own currency.

Check them

Change them, with your approval

How are changes approved?

1. The AI proposes a change. The server reads the live values, checks your limits, and asks Google to test the change without applying it.
2. A page opens in your browser, on your computer only. It shows the account, the exact change, every campaign it touches, and the AI's reason in a separate box marked “unverified”.
3. You approve with the 6-character code from that page, or you reject the change. An AI saying “yes” approves nothing.
4. The change is sent once. Then the server reads the account again to confirm it landed, and it logs every step.

Changes are off until you switch them on for an account in your policy file. That file also sets your spend limits, how big a budget step can be, and a kill switch that stops every change.

What does a check look like?

Here's the real answer from the explain_check tool for check SK05. It looks for search terms that spend past a set amount without a single sale.

{
  "id": "SK05",
  "title": "search term spends past the waste bar without a conversion",
  "group": "search",
  "noneFoundMeans": "No search term spends past the bar without a sale.",
  "requires": [
    "searchTerms",
    "campaigns"
  ],
  "dependsOn": [
    "searchTerms",
    "adGroups",
    "campaigns",
    "dailyMetrics"
  ],
  "producedBy": [
    {
      "table": "searchTerms",
      "section": "search_terms"
    },
    {
      "table": "adGroups",
      "section": "ad_groups"
    },
    {
      "table": "campaigns",
      "section": "campaigns"
    },
    {
      "table": "dailyMetrics",
      "section": "daily_metrics"
    }
  ],
  "settings": {
    "floors.wasteBandUnder1kUsd": 20,
    "floors.wasteBand1kTo10kUsd": 50,
    "floors.wasteBand10kTo50kUsd": 100,
    "floors.wasteBand50kPlusUsd": 200
  },
  "maxSeverity": "warning",
  "emitsFindings": true,
  "infoLine": null,
  "whenNotRun": [
    "Not run when any table it depends on (searchTerms, adGroups, campaigns, dailyMetrics) was not read, failed, was refused by Google, was cut (a sample) or points at missing parents.",
    "Not run when its own floors are not met (too little spend, too few conversions, too new) or when nothing it judges exists on the account."
  ]
}

The bar goes up with the size of the account, from $20 to $200. When the data is missing or too thin, the check says “not run” and gives the reason. For a problem worked through step by step, read Performance Max spending but no sales.

How do I install it?

Setup takes about 15 minutes, plus Google's review of your access request.

1. Install Node.js 22.13 or later.
2. In Google Cloud, make a project, turn on the Google Ads API, and make an OAuth client of the type “Desktop app”. OAuth is Google's standard sign-in for apps.
3. On the Google Ads API page of that project, apply for Explorer access. Until Google approves it, only test accounts work.
4. In a terminal, run npx -y perfoads-mcp@0.2.0-alpha.0 init. It asks for your OAuth client, opens Google's sign-in, saves the sign-in encrypted, and prints the settings for your AI app.
5. Add it to your AI app. For Claude Code, run:

   claude mcp add --scope user perfoads-mcp -- npx -y perfoads-mcp@0.2.0-alpha.0 serve

   For Claude Desktop and Cursor, paste the settings init printed. They look like this:

   {
     "mcpServers": {
       "perfoads-mcp": {
         "command": "npx",
         "args": ["-y", "perfoads-mcp@0.2.0-alpha.0", "serve"]
       }
     }
   }

   For the ChatGPT desktop app and Codex, follow the setup guide.
6. Ask your AI: “Check my PerfoAds setup.” It tests the sign-in, your access level and your policy file, and says what to fix.

Every step in detail: the setup guide on GitHub.

What can't it do?

• It doesn't work in ChatGPT on the web. That needs a remote server, and PerfoAds MCP runs on your computer. The ChatGPT desktop app and Codex both work.
• It doesn't give fix advice. It says what's wrong, with the evidence.
• Explorer access allows 2,880 operations a day on live accounts. Keyword ideas need Basic or Standard access.
• If your Google Cloud app stays in “Testing” mode, Google ends the sign-in after 7 days. The setup guide shows how to avoid that.
• It's an early release. It has passed live tests on a Google Ads test account, and read-only runs on real accounts.

Where does my data go?

Who built it?

Pawel Wilk, founder of PerfoAds. He's run Google Ads for about 7 years and managed millions of dollars in ad spend. PerfoAds is a one-person company in Warsaw, so your questions reach him directly.

Frequently asked questions