> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brama.work/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Ads

> Аналітика рекламних кампаній через AI-агента – service-account (Bring-Your-Own).

<Note>
  **Status: live.** 6 MCP tools: 4 read-only (аналіз кампаній, метадані полів, ідеї ключових слів, список акаунтів) + 2 write через **draft → confirm** (пауза / відновлення кампанії, лише для allowlisted-акаунтів).
</Note>

## Як це працює

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

1. Створи (або обери) GCP-проєкт. Для Mode A – **окремий проєкт** (напр. `mcp-ads`), не клієнтський
2. **APIs & Services → Library → Google Ads API → Enable**
3. **IAM & Admin → Service Accounts → Create** (GCP-ролі **не** потрібні – доступ дається через Google Ads, не IAM)
4. У SA → **Keys → Add key → Create new key → JSON** → завантажиться `*.json`
5. Скопіюй **email SA** (`name@project.iam.gserviceaccount.com`)

### 2. Developer token

З **MCC → Tools → Setup → API Center** ([ads.google.com/aw/apicenter](https://ads.google.com/aw/apicenter), увійди в manager-акаунт) → скопіюй **Developer token**. Новий = Test access; для реальних даних подай заявку на **Basic access**. ([docs](https://developers.google.com/google-ads/api/docs/get-started/dev-token))

### 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`](https://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 цифр)   | **порожньо** |

→ **Connect**. Brama одразу перевіряє доступ до Google Ads при підключенні – якщо креди невалідні або SA не має доступу, побачиш помилку до збереження. Зберігається зашифрованим; Brama ніколи не показує креди назад (лише статус «active»).

### 5. Запит

У своєму MCP клієнті (Claude Desktop, Gemini CLI, чи будь-який інший – див. [Quickstart](/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)

<Card title="brama_googleads_list_accounts" icon="building">
  Список Google Ads акаунтів, до яких має доступ підключений акаунт. Виклич **першим**, щоб дізнатися, який `customer_id` запитувати.

  **Параметри:** немає.

  **Повертає:** для кожного акаунта – `customer_id`, `descriptive_name`, `is_manager` (Manager/MCC-акаунти не містять метрик самі – запитуй їхні клієнтські акаунти) і `manager_customer_id` (це `login_customer_id`, який треба передати у `brama_googleads_run_gaql`, коли акаунт доступний через MCC).
</Card>

<Card title="brama_googleads_run_gaql" icon="chart-line">
  Виконує [GAQL](https://developers.google.com/google-ads/api/docs/query/overview)-запит (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`.

  <Warning>Read-only. Tool **не** змінює кампанії/бюджети.</Warning>
</Card>

<Card title="brama_googleads_field_metadata" icon="table-list">
  Описує поля ресурсу Google Ads, доступні для запиту. За назвою ресурсу (напр. `campaign`, `ad_group`, `keyword_view`) повертає поля, які можна SELECT, фільтрувати (WHERE) і сортувати (ORDER BY) – разом із сумісними `metrics.*` і `segments.*`.

  **Параметри:** назва ресурсу *(required)*.

  Use: перед написанням `brama_googleads_run_gaql`, щоб не вгадувати назви полів. Read-only.
</Card>

<Card title="brama_googleads_generate_keyword_ideas" icon="lightbulb">
  Генерує ідеї ключових слів для keyword research. За seed-словами та/або URL лендінгу повертає схожі ключові слова з середньою кількістю запитів на місяць, рівнем конкуренції та оцінкою ставки top-of-page (у micros).

  **Параметри:** seed-слова та/або URL *(хоча б одне)*, `language_id` *(optional)*, `geo_target_ids` *(optional)*.

  Use: планування SEO / SEM. Read-only – генерує ідеї, нічого не створює.
</Card>

### Зміни (draft → confirm)

<Note>
  Write-tools нижче працюють через **draft → confirm**: tool готує зміну і показує у MCP клієнті інтерактивну картку (назва кампанії + поточний статус + запитувана зміна + **Confirm / Cancel**). Нічого не змінюється, поки ти не натиснеш **Confirm**. Прямого «apply без підтвердження» tool'а навмисно немає. Write доступний **лише для allowlisted-акаунтів** – якщо акаунт не в allowlist'і, картка повертається заблокованою (зміна не готується).
</Note>

<Card title="brama_googleads_set_campaign_status_draft" icon="circle-pause">
  Готує **паузу** або **відновлення** кампанії і показує картку підтвердження. Пауза зупиняє показ оголошень кампанії; відновлення (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: "постав кампанію на паузу", "віднови кампанію".
</Card>

<Card title="brama_googleads_confirm_action" icon="circle-check">
  Виконує зміну, яку підготував draft (паузу або відновлення кампанії). Крок **Confirm** із картки.

  **Параметри:** `confirm_token` *(required – з draft)*.

  Одноразовий: не повторювати після успіху. На клієнтах, що рендерять картку, викликається **лише** кнопкою Confirm – модель не може підтвердити сама.
</Card>

## Безпека

* 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`.