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)

Четене

Инструмент	За какво
list_accounts	Цялото дърво под MCC-то. Оттук вадиш customerId.
run_gaql	Произволна GAQL заявка. Основният read инструмент.
run_gaql_multi	До 20 заявки паралелно, може срещу различни акаунти.
describe_fields	Метаданни за GAQL полета - вместо да гадаеш имена.
account_overview	Готов одит на акаунт с едно извикване.
change_history	Историята от Google, включително ръчните промени в UI-я.

Писане

Инструмент	За какво
mutate	Сурови операции, всякакъв ресурс. По подразбиране validateOnly.
set_status	Bulk pause/enable/remove на кампании, ad groups, реклами, думи.
set_campaign_budget	Дневен бюджет, с проверка за споделен бюджет.
set_bid	CPC бидове, bulk.
add_keywords	Позитивни думи в ad group.
add_negative_keywords	Негативни думи на ниво кампания или ad group.
create_responsive_search_ad	RSA, по подразбиране PAUSED.

Контрол

Инструмент	За какво
list_changes	Локалният change log, с ID за връщане назад.
undo_change	Връща промяна назад от снимката ѝ.
get_guardrails / set_guardrails	Предпазните правила.
check_connection	Диагностика.

---

Безопасност

Всяко писане минава през 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