Skip to main content

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.

Status: live, closed beta, agency-assisted onboarding. 1 read-only MCP tool (brama_googleads_run_gaql). Підключення робиться разом з агенцією Bystrov.

​
Як це працює

Brama не є Google-застосунком. Ти створюєш власний Google Cloud service account, даєш йому Read-only доступ у Google Ads, і передаєш Brama цей ключ + developer token. Креди зберігаються зашифрованими (ключі поза базою), на диск не пишуться, розшифровуються лише в пам’яті на час запиту. Менше кроків ніж OAuth (нема refresh-token-флоу), least privilege (Read-only). Є два режими — обери під свою ситуацію:
Mode A — Agency / MCC-level (рекоменд. для агенції)Mode B — Per-account (ізольований)
Що покриваєвсі клієнтські акаунти під одним MCC, один Connectодин конкретний Ads-акаунт
SA доданийRead-only на MCC (manager)Read-only на операційний акаунт
Login customer ID у форміID MCCпорожньо
Ізоляціяодин connect = доступ до всіх child-акаунтів MCC (свідомий agency trade-off)доступ лише до того акаунта

​
Спільні кроки (обидва режими)

​
1. Google Cloud — проєкт + service account

  1. Створи (або обери) GCP-проєкт. Для Mode A — окремий агенційний проєкт (напр. bystrov-mcp), не клієнтський
  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, увійди в 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 AMode B
Service account JSON keyвесь .json з кроку 1те саме
Developer tokenз кроку 2те саме
Login customer ID (MCC)ID MCC (10 цифр)порожньо
→ Connect. Зберігається зашифрованим; Brama ніколи не показує креди назад (лише статус «active»).

​
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 tool (live)

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 одиниця валюти).
Read-only. Tool не змінює кампанії/бюджети.

​
Безпека

  • Brama не Google-OAuth-застосунок → CASA / Google verification не застосовується.
  • SA має лише Read-only (least privilege).
  • SA JSON key — зашифровано at rest, ключі поза базою; на диск не пишеться, у пам’яті лише на час запиту.
  • Кожен tenant ізольований.
  • Mode A нюанс: один Brama-connect на MCC = доступ до всіх child-акаунтів цього MCC через один токен. Це свідомий agency-operated trade-off — обирай Mode B якщо потрібна ізоляція по акаунту.

​
Питання

Підключення проходить разом з агенцією Bystrov. Напиши viktor@brama.work.