Відкритий код

MCP-сервер для Google Ads, який ви розгортаєте самі

42 інструменти, щоб ChatGPT або Claude керували вашими акаунтами Google Ads — читали показники, шукали ключові слова, збирали кампанії, змінювали бюджети — за обмеженнями, які модель не здатна обійти вмовляннями.

Уперше з цим стикаєтеся? У нашому поясненні розказано, що таке MCP-сервер для Google Ads, що він може відкривати і що варто перевірити, перш ніж йому довіряти. Читати пояснення про MCP-сервер

• 42 інструменти
• Ліцензія MIT
• Java 21 · Spring Boot

Чому це складніше, ніж здається

Токени розробника спершу обмежені

Новий токен розробника Google Ads має доступ Test Account і дістає лише тестові акаунти. Ваш перший правильний запуск повертає порожні списки й виглядає як помилка. Доступ Basic вимагає заявки, а розгляд триває кілька днів — тож почніть саме з нього.

Керуючі акаунти не містять кампаній

Google повертає переважно керуючі акаунти (MCC), які не можуть показувати рекламу. Показувати можуть їхні дочірні акаунти, і до кожного треба звертатися, вказавши того керуючого, через якого його знайдено.

API говорить у micros

Суми надходять у мільйонних частках. Бюджет 5000000 — це п'ять одиниць валюти, а помилка в мільйон разів — це не округлення, а інцидент із витратами.

Суми не несуть валюти

У відповіді ніде не сказано, у якій валюті число. Якщо показати бюджет акаунта в UAH зі знаком долара, читач побачить суму приблизно в сорок разів більшу за справжню.

GAQL — це не SQL

Тут немає join, а сегментація змінює те, що означає рядок, а не лише їхню кількість. Попросіть не той розріз — і ваші підсумки тихо помножаться.

Версії вимикають, а не позначають застарілими

Google відключає старі версії API за опублікованим графіком. Жорстко зафіксована версія просто перестає працювати певного дня, тож її має бути можливо змінити, не чекаючи нового релізу.

Чого він не робитиме

Варто прочитати до команди встановлення, бо помилка тут витрачає справжні гроші.

• Ніщо не запускається саме. Інструмент створення кампанії не має поля статусу у своїй схемі, тому модель не може створити активну кампанію навіть якщо спробує.
• Активувати можна лише кампанії, які створив цей сервер. Створену в інтерфейсі Google Ads він відхилить, бо її бюджет ніколи не проходив перевірку ліміту.
• Кожна зміна бюджету порівнюється з лімітом, який задали ви, у валюті самого рекламного акаунта. Сервер відхиляє зміну, а не занижує її тихо, щоб вона вмістилася.
• У кожного інструмента запису є денний ліміт, тож модель, що зациклилася, не зробить сотні змін в одному акаунті.
• Окремий захист відхиляє серію викликів за короткий час, незалежно від інструмента.
• Типово він автентифікує одного оператора: один пароль і один акаунт, а не багатокористувацький вхід, який вам довелося б захищати.

Як це поєднано

mcp-core

Шар протоколу й невеликий сервер авторизації OAuth 2.1: динамічна реєстрація клієнтів, PKCE, ротація refresh-токенів із виявленням повторного використання та екран згоди. Він нічого не знає про рекламу, тож підходить для будь-яких інструментів, які має викликати асистент.

клієнт google-ads

Звичайний клієнт API Google Ads без Spring і без MCP. Його можна використовувати окремо з будь-якого коду, якому потрібно звертатися до Google Ads, і саме тому він виходить окремим артефактом.

сервер google-ads

Той самий запускний сервер: 42 інструменти, обмеження витрат, журнал аудиту кожного запису та процес підключення акаунта Google Ads.

42 інструменти

Інструментам читання потрібен доступ на читання; інструментам запису — доступ на запис, і вони проходять через обмеження вище.

• Акаунти, білінг і темп витрат — Перелічити доступні акаунти, перевірити налаштування білінгу й побачити сьогоднішні витрати проти бюджету кожної кампанії.
• Кампанії — Перелічити, створити на паузі, активувати, поставити на паузу, відновити та змінити бюджети, стратегії ставок, налаштування, таргетинг, мінус-слова й цілі конверсій.
• Групи оголошень і оголошення — Створювати й редагувати групи оголошень, переглядати окремі оголошення з вердиктом щодо політик, створювати та оновлювати адаптивні оголошення в пошуку.
• Ключові слова й пошукові запити — Перелічувати, додавати, видаляти та редагувати ключові слова, читати запити, які люди справді вводили, і отримувати ідеї ключових слів.
• Performance Max — Читати й редагувати групи ресурсів, їхні ресурси та медіа, пошукові теми й ресурси бренду на рівні кампанії.
• Додаткові посилання — Перелічувати, створювати, оновлювати та видаляти додаткові посилання на рівні кампанії.
• Звіти — Показники за акаунтом, кампанією, групою оголошень або ключовим словом, а також за географією, аудиторіями й діями-конверсіями.

Запустити самостійно

Опублікованому образу не потрібні ні Java, ні збірка. Скопіюйте приклад файлу середовища, заповніть його й запустіть: кожне значення описане там само, де ви його задаєте.

# 1. the compose file and the documented environment template
curl -O https://raw.githubusercontent.com/loomascale/ads-mcp/main/docker-compose.yml
curl -O https://raw.githubusercontent.com/loomascale/ads-mcp/main/.env.example

# 2. fill it in — every value says what it is and how to generate it
cp .env.example .env

# 3. start it; the image is prebuilt, so there is no JDK and no Maven here
docker compose up

curl -s -X POST https://your-host/mcp \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq '.result.tools[].name'

Одна вимога радше повільна, ніж складна: токен розробника Google Ads потребує заявки до Google, а розгляд триває кілька днів. Почніть із цього раніше за все інше.

Питання