google-ads-mcp

Собствен MCP сървър към Google Ads API. Дава ти Google Ads директно в терминала през Claude Code: питаш на човешки език, а сървърът превежда въпроса в GAQL заявка или в mutate операция срещу реалния акаунт.

Заменя платените wrapper-и, които таксуват на „connected account". Тук цената е нула - Google Ads API е безплатен, а един MCC покрива всичките си дъщерни акаунти.

Node, нула зависимости освен MCP SDK-то. Използва вградения fetch и REST-а на Google Ads API, без protobuf библиотеката.

Инсталация: виж SETUP.md. Там е целият процес от нула - Node, developer token, Google Cloud, OAuth, вързване към Claude Code и проверка, че работи.

Инструменти (18)

Четене

Писане

Контрол

Related MCP server: google-ads-mcp

Безопасност

Всяко писане минава през src/apply.js: guardrails → снимка на старите стойности → mutate → запис в change log.

Guardrails (~/.google-ads-mcp/guardrails.json):

{
  "readOnlyAccounts": [],
  "blockedAccounts": [],
  "writeAllowlist": [],
  "maxBudgetIncreasePct": 50,
  "maxDailyBudget": null,
  "requireConfirmForRemove": true,
  "maxOperationsPerCall": 500
}

writeAllowlist е най-силният предпазител: ако не е празен, писане е позволено само в изброените акаунти. Сложи един тестов акаунт, докато свикнеш, и всички останали са защитени.

Undo (~/.google-ads-mcp/changes.jsonl) - преди всеки update се снима старата стойност на полетата от updateMask, за да може undo_change да я върне.

Две честни ограничения:

• REMOVE е необратим. Google Ads API няма un-remove. Затова set_status с REMOVED иска confirm: true, а по подразбиране се препоръчва PAUSED.

• Полета, които не са четими през GAQL, не могат да се снимат. Тогава промяната се записва в лога, но list_changes я маркира undoable: false.

Поддръжка

Версия на API-то. По подразбиране v24. Google мина на месечен цикъл през 2026. Всяка версия живее около година. Смяната е един ред в ~/.google-ads.env:

GOOGLE_ADS_API_VERSION=v25

Тест след промени:

npm test        # MCP handshake, схеми, guardrails - не пипа мрежата
npm run doctor  # реална връзка към Google

Файлове

google-ads-mcp/
  SETUP.md              инсталация от нула
  src/index.js          MCP сървър, регистрация на инструментите
  src/config.js         зареждане на ~/.google-ads.env
  src/auth.js           OAuth refresh + кеш на access token
  src/client.js         REST слой (searchStream, mutate, грешки)
  src/apply.js          guardrails → снимка → mutate → лог
  src/guardrails.js     предпазни правила
  src/changelog.js      change log и undo
  src/tools/            read.js · write.js · ops.js
  bin/oauth.js          еднократен OAuth flow
  bin/doctor.js         диагностика от терминала
  test/smoke.mjs        offline тест

~/.google-ads.env       креденшъли (chmod 600)
~/.google-ads-mcp/      guardrails.json · changes.jsonl