Status: live. 6 MCP tools: 4 read-only (аналіз кампаній, метадані полів, ідеї ключових слів, список акаунтів) + 2 write через draft → confirm (пауза / відновлення кампанії, лише для allowlisted-акаунтів).
Як це працює
Brama не є Google-застосунком. Ти створюєш власний Google Cloud service account, даєш йому Read-only доступ у Google Ads, і передаєш Brama цей ключ + developer token. Креди зберігаються зашифрованими (ключі поза базою), на диск не пишуться, розшифровуються лише в пам’яті на час запиту. Менше кроків ніж OAuth (нема refresh-token-флоу), least privilege (Read-only). Є два режими – обери під свою ситуацію:| Mode A – MCC-level (керування кількома акаунтами) | Mode B – Per-account (ізольований) | |
|---|---|---|
| Що покриває | всі клієнтські акаунти під одним MCC, один Connect | один конкретний Ads-акаунт |
| SA доданий | Read-only на MCC (manager) | Read-only на операційний акаунт |
Login customer ID у формі | ID MCC | порожньо |
| Ізоляція | один connect = доступ до всіх child-акаунтів MCC (свідомий MCC trade-off) | доступ лише до того акаунта |
Спільні кроки (обидва режими)
1. Google Cloud – проєкт + service account
- Створи (або обери) GCP-проєкт. Для Mode A – окремий проєкт (напр.
mcp-ads), не клієнтський - APIs & Services → Library → Google Ads API → Enable
- IAM & Admin → Service Accounts → Create (GCP-ролі не потрібні – доступ дається через Google Ads, не IAM)
- У SA → Keys → Add key → Create new key → JSON → завантажиться
*.json - Скопіюй email SA (
name@project.iam.gserviceaccount.com)
2. Developer token
З MCC → Tools → Setup → API Center (ads.google.com/aw/apicenter, увійди в manager-акаунт) → скопіюй Developer token. Новий = Test access; для реальних даних подай заявку на Basic access. (docs)3. Дай SA доступ у Google Ads
- Mode A: Google Ads → увійди в MCC → Admin → Access and security → + → встав email SA → Read only. Доступ каскадить на всі child-акаунти MCC.
- Mode B: те саме, але на конкретному операційному акаунті, не на MCC.
4. Підключити в Brama
app.brama.work → Dashboard → Google Ads → Connect:
| Поле | Mode A | Mode B |
|---|---|---|
| Service account JSON key | весь .json з кроку 1 | те саме |
| Developer token | з кроку 2 | те саме |
| Login customer ID (MCC) | ID MCC (10 цифр) | порожньо |
5. Запит
У своєму MCP клієнті (Claude Desktop, Gemini CLI, чи будь-який інший – див. Quickstart):
Google Ads GAQL по customer {customer_id}: SELECT campaign.name, metrics.cost_micros, metrics.clicks FROM campaign WHERE segments.date DURING LAST_7_DAYS
- Mode A:
customer_id= child-акаунт під MCC (10 цифр) – завжди вказуй явно (поле login_customer_id у цьому режимі = тільки routing, не дефолтний акаунт; сам MCC кампаній не має). - Mode B: якщо login_customer_id порожній – теж вказуй customer_id у запиті; інакше отримаєш guard-помилку
No customer_id given.
MCP tools (live)
Читання (read-only)
brama_googleads_list_accounts
Список Google Ads акаунтів, до яких має доступ підключений акаунт. Виклич першим, щоб дізнатися, який
customer_id запитувати.Параметри: немає.Повертає: для кожного акаунта – customer_id, descriptive_name, is_manager (Manager/MCC-акаунти не містять метрик самі – запитуй їхні клієнтські акаунти) і manager_customer_id (це login_customer_id, який треба передати у brama_googleads_run_gaql, коли акаунт доступний через MCC).brama_googleads_run_gaql
Виконує GAQL-запит (read-only). Для аналізу реклами: кампанії, групи оголошень, ключові слова, витрати, конверсії, покази, кліки.Параметри:
query (required), customer_id (optional – дефолт = login_customer_id; у Mode A вказуй child явно)Приклад: SELECT campaign.name, metrics.cost_micros, metrics.clicks FROM campaign WHERE segments.date DURING LAST_7_DAYSВитрати – у micros (1 000 000 micros = 1 одиниця валюти). Метрики доступні лише на клієнтських акаунтах; MCC поверне REQUESTED_METRICS_FOR_MANAGER.brama_googleads_field_metadata
Описує поля ресурсу Google Ads, доступні для запиту. За назвою ресурсу (напр.
campaign, ad_group, keyword_view) повертає поля, які можна SELECT, фільтрувати (WHERE) і сортувати (ORDER BY) – разом із сумісними metrics.* і segments.*.Параметри: назва ресурсу (required).Use: перед написанням brama_googleads_run_gaql, щоб не вгадувати назви полів. Read-only.brama_googleads_generate_keyword_ideas
Генерує ідеї ключових слів для keyword research. За seed-словами та/або URL лендінгу повертає схожі ключові слова з середньою кількістю запитів на місяць, рівнем конкуренції та оцінкою ставки top-of-page (у micros).Параметри: seed-слова та/або URL (хоча б одне),
language_id (optional), geo_target_ids (optional).Use: планування SEO / SEM. Read-only – генерує ідеї, нічого не створює.Зміни (draft → confirm)
Write-tools нижче працюють через draft → confirm: tool готує зміну і показує у MCP клієнті інтерактивну картку (назва кампанії + поточний статус + запитувана зміна + Confirm / Cancel). Нічого не змінюється, поки ти не натиснеш Confirm. Прямого «apply без підтвердження» tool’а навмисно немає. Write доступний лише для allowlisted-акаунтів – якщо акаунт не в allowlist’і, картка повертається заблокованою (зміна не готується).
brama_googleads_set_campaign_status_draft
Готує паузу або відновлення кампанії і показує картку підтвердження. Пауза зупиняє показ оголошень кампанії; відновлення (ENABLED) вмикає її знову. Зміна зворотна. Перед показом картки перевіряє, що акаунт має право на зміну (під час перевірки нічого не змінюється).Параметри:
customer_id (required – клієнтський акаунт із brama_googleads_list_accounts), campaign_id (required – з brama_googleads_run_gaql), status (required: PAUSED або ENABLED), login_customer_id (optional – MCC для автентифікації).Use: “постав кампанію на паузу”, “віднови кампанію”.brama_googleads_confirm_action
Виконує зміну, яку підготував draft (паузу або відновлення кампанії). Крок Confirm із картки.Параметри:
confirm_token (required – з draft).Одноразовий: не повторювати після успіху. На клієнтах, що рендерять картку, викликається лише кнопкою Confirm – модель не може підтвердити сама.Безпека
- Brama не Google-OAuth-застосунок → CASA / Google verification не застосовується.
- SA має лише Read-only (least privilege).
- SA JSON key – зашифровано at rest, ключі поза базою; на диск не пишеться, у пам’яті лише на час запиту.
- Кожен tenant ізольований.
- Mode A нюанс: один Brama-connect на MCC = доступ до всіх child-акаунтів цього MCC через один токен. Це свідомий MCC trade-off – обирай Mode B якщо потрібна ізоляція по акаунту.
Питання
Питання? Напишиviktor@brama.work.