> ## 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 Search Console

> Пошукова ефективність сайту через AI-агента – Search Console API, Shared App OAuth, read-only.

<Note>
  **Status: live.** 6 read-only MCP tools на Google Search Console API.
</Note>

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

Google Search Console інтеграція використовує **Shared App** OAuth: Brama тримає **один** OAuth-застосунок – ти просто натискаєш Connect, нічого створювати у Google Cloud не треба. Після стандартного Google consent твоя інтеграція переходить у статус **Active**.

Scope – `webmasters.readonly`. Google класифікує його як **non-sensitive**, тому окрема верифікація застосунку не потрібна, і ти не побачиш екран попередження. Доступ – суто **read-only**: Brama лише читає дані пошукової ефективності й нічого не змінює у Search Console.

Токени зберігаються **зашифрованими** (envelope encryption, ключі поза базою), ізольовано per-tenant. Brama персистить ротовані refresh-токени автоматично – повторний consent при звичайній роботі не потрібен.

## Підключення

### 1. Connect

[`app.brama.work`](https://app.brama.work) → **Integrations → Google Search Console** → натисни **Connect**.

Brama редіректить тебе на Google OAuth consent screen. Надай доступ із scope **"View Search Console data for your verified sites"** і повернешся у Brama – інтеграція стане `active`.

На акаунті повинен бути принаймні один verified site (domain property або URL-prefix property) – без верифікованих сайтів tools повернуть порожній список.

### 2. Запит

У своєму MCP клієнті (Claude Desktop, Gemini CLI – див. [Connect a client](/connect)):

> Які пошукові запити приносили найбільше кліків минулого місяця?

Агент викличе `brama_gsc_top_queries` і поверне запити з кліками, показами, CTR та середньою позицією.

## MCP tools (live)

Усі 6 tools – **read-only**, на Search Console API. Нічого не змінюють у Google Search Console.

<Note>
  Дані Search Console мають затримку **\~2–3 дні**, а історія сягає максимум **16 місяців** назад.
</Note>

<Card title="brama_gsc_list_sites" icon="list">
  Список сайтів (properties) Search Console, до яких має доступ підключений акаунт, з рівнем дозволу для кожного.

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

  Use: дізнатися `site_url` (наприклад `sc-domain:example.com` або `https://example.com/`), який передається в інші GSC tools. Виклич першим.
</Card>

<Card title="brama_gsc_search_analytics" icon="chart-bar">
  Гнучкий звіт пошукової ефективності за діапазон дат, згрупований за одним чи кількома вимірами. Повертає рядки з кліками, показами, CTR та середньою позицією.

  **Параметри:**

  * `site_url` *(required)* – з `brama_gsc_list_sites`
  * `start_date` *(required)* – ISO `YYYY-MM-DD`
  * `end_date` *(required)* – ISO `YYYY-MM-DD`
  * `dimensions` *(optional)* – будь-які з `query`, `page`, `country`, `device`, `date` (default `[query]`)
  * `row_limit` *(optional)* – default 25, max 1000

  Use: "топ запитів за минулий місяць", "які сторінки дають найбільше органіки", "mobile vs desktop".
</Card>

<Card title="brama_gsc_top_queries" icon="magnifying-glass">
  Швидкий ярлик: топ пошукових запитів, що приводили користувачів на сайт за діапазон дат (search\_analytics, згруповане за `query`). Повертає запит, кліки, покази, CTR, середню позицію.

  **Параметри:**

  * `site_url` *(required)*
  * `start_date` *(required)* – ISO `YYYY-MM-DD`
  * `end_date` *(required)* – ISO `YYYY-MM-DD`
  * `row_limit` *(optional)* – default 25, max 1000

  Use: "які запити приносять найбільше кліків?".
</Card>

<Card title="brama_gsc_top_pages" icon="file-text">
  Швидкий ярлик: топ сторінок сайту за органічною ефективністю за діапазон дат (search\_analytics, згруповане за `page`). Повертає URL сторінки, кліки, покази, CTR, середню позицію.

  **Параметри:**

  * `site_url` *(required)*
  * `start_date` *(required)* – ISO `YYYY-MM-DD`
  * `end_date` *(required)* – ISO `YYYY-MM-DD`
  * `row_limit` *(optional)* – default 25, max 1000

  Use: "які сторінки найкраще ранжуються в пошуку?".
</Card>

<Card title="brama_gsc_inspect_url" icon="magnifying-glass-chart">
  Інспекція індексного статусу однієї URL (URL Inspection). Відповідає на питання "чи проіндексована ця сторінка, і якщо ні – чому?": index verdict та coverage state (напр. "Submitted and indexed"), час останнього сканування, Google-обраний canonical vs твій оголошений, стан robots.txt / indexing / page-fetch, які sitemap-и її посилаються, плюс mobile-usability та rich-results verdicts.

  **Параметри:**

  * `site_url` *(required)* – property з `brama_gsc_list_sites`
  * `inspection_url` *(required)* – повна URL для інспекції (має належати цьому property)
  * `language_code` *(optional)* – BCP-47, default `en-US`

  Use: "чому ця сторінка не в індексі?", "який canonical обрав Google?".
</Card>

<Card title="brama_gsc_list_sitemaps" icon="sitemap">
  Список sitemap-ів, поданих для property Search Console: тип, час останнього подання та останнього завантаження, pending-прапорець, кількість warnings та errors, а також submitted vs indexed кількість URL.

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

  Use: "чи здорові мої sitemap-и?", "скільки URL проіндексовано з sitemap?".
</Card>

## Приклади запитів агенту

* "Які пошукові запити приносили найбільше кліків минулого місяця?"
* "Покажи топ-сторінки за органічним пошуком за квартал."
* "Чи проіндексована сторінка example.com/pricing?"
* "Mobile vs desktop ефективність за останні 28 днів."
* "Чи здорові мої sitemap-и – скільки URL проіндексовано?"

## Безпека

* **Shared App** – Brama тримає єдиний OAuth-застосунок; tenant'у НЕ потрібно нічого створювати у Google Cloud.
* Scope – **read-only** (`webmasters.readonly`), non-sensitive. Brama не може змінювати дані, sitemap-и чи налаштування Search Console.
* Токени зашифровані at rest (envelope encryption), ключі поза базою; на диск не пишуться, у пам'яті лише на час запиту; у логи не потрапляють.
* Brama персистить ротовані refresh-токени автоматично – повторний consent при звичайній роботі не потрібен.
* Кожен tenant ізольований – твої Search Console дані недосяжні іншим tenant'ам.

## Питання

Питання? Напиши `viktor@brama.work`.