Skip to main content
Status: live. 6 read-only MCP tools на Google Search Console API.

Як це працює

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 → 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):
Які пошукові запити приносили найбільше кліків минулого місяця?
Агент викличе brama_gsc_top_queries і поверне запити з кліками, показами, CTR та середньою позицією.

MCP tools (live)

Усі 6 tools – read-only, на Search Console API. Нічого не змінюють у Google Search Console.
Дані Search Console мають затримку ~2–3 дні, а історія сягає максимум 16 місяців назад.

brama_gsc_list_sites

Список сайтів (properties) Search Console, до яких має доступ підключений акаунт, з рівнем дозволу для кожного.Параметри: немає.Use: дізнатися site_url (наприклад sc-domain:example.com або https://example.com/), який передається в інші GSC tools. Виклич першим.

brama_gsc_search_analytics

Гнучкий звіт пошукової ефективності за діапазон дат, згрупований за одним чи кількома вимірами. Повертає рядки з кліками, показами, 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, searchAppearance, hour (default [query]). hour автоматично вмикає data_state: hourly_all і покриває лише останні дні
  • search_type (optional) – web (default), image, video, news, discover, googleNews. У Discover і Google News немає запитів – групуй за page, country, device, date
  • filters (optional) – список фільтрів, усі мають збігтися (AND). Кожен: dimension (query, page, country, device, searchAppearance), operator (equals default, notEquals, contains, notContains, includingRegex, excludingRegex), expression. contains не чутливий до регістру, equals – чутливий для query і page; regex – синтаксис RE2, (?i) для нечутливості до регістру
  • data_state (optional) – final (default, лише фіналізовані дні), all (плюс свіжі, ще неповні дні), hourly_all
  • aggregation_type (optional) – auto (default), byPage, byProperty (неможливий разом із page, не підтримується для Discover/Google News)
  • row_limit (optional) – default 25, max 5000
  • start_row (optional) – зсув першого рядка (від 0). Відповідь містить has_more і next_start_row – передай його сюди, щоб отримати наступну сторінку тих самих даних
Use: “топ запитів за минулий місяць”, “брендові vs небрендові запити” (includingRegex / excludingRegex по query), “ефективність у Discover”, “які rich-результати дають кліки” (searchAppearance), “погодинний трафік за вчора” (hour), “повний список запитів” (row_limit: 5000 + start_row).Приклад брендового зрізу:
Той самий запит з excludingRegex дає небрендову частину.

brama_gsc_top_queries

Швидкий ярлик: топ пошукових запитів, що приводили користувачів на сайт за діапазон дат (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 5000
Use: “які запити приносять найбільше кліків?”.

brama_gsc_top_pages

Швидкий ярлик: топ сторінок сайту за органічною ефективністю за діапазон дат (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 5000
Use: “які сторінки найкраще ранжуються в пошуку?”.

brama_gsc_inspect_url

Інспекція індексного статусу однієї 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?”.

brama_gsc_list_sitemaps

Список sitemap-ів, поданих для property Search Console: тип, час останнього подання та останнього завантаження, pending-прапорець, кількість warnings та errors, а також submitted vs indexed кількість URL.Параметри: site_url (required) – з brama_gsc_list_sites.Use: “чи здорові мої sitemap-и?”, “скільки URL проіндексовано з sitemap?”.

brama_gsc_get_sitemap

Деталі одного поданого sitemap: submitted vs indexed у розрізі типів контенту (web, image, video, news), warnings та errors, pending-прапорець, час подання й завантаження. Якщо це sitemap-індекс – додатково таблиця дочірніх sitemap-ів з їхніми лічильниками.Параметри:
  • site_url (required) – з brama_gsc_list_sites
  • sitemap_url (required) – повна URL sitemap, як у колонці path з brama_gsc_list_sitemaps
Use: “що всередині sitemap-індексу?”, “скільки зображень із sitemap проіндексовано?”, “у якого дочірнього sitemap помилки?”.

brama_gsc_inspect_urls

Пакетна URL Inspection: до 50 URL за один виклик і одна зведена таблиця – verdict (PASS = в індексі), coverage state, indexing state, час останнього сканування та чи збігається Google-обраний canonical з перевіреною URL.Параметри:
  • site_url (required)
  • urls (optional) – список URL, max 50 – або
  • sitemap_url (optional) – публічний sitemap цього property (не індекс – візьми дочірній з brama_gsc_get_sitemap); його URL читаються й перевіряються. Великий sitemap проходиться зрізами через start і limit (відповідь містить загальну кількість і наступний start)
  • language_code (optional) – BCP-47, default en-US
Усі URL мають належати property. Квота Search Console – 2000 перевірок на property на день і 600 на хвилину: при вичерпанні повертаються вже перевірені рядки, решта позначена як неперевірена – повтори пізніше.Use: “чи всі сторінки колекцій в індексі після міграції теми?”, “які товари випали з індексу?”, “перевір кожну URL цього sitemap”.

Зміни в Search Console (за підтвердженням)

За замовчуванням підключення лише читає. Власник вмикає запис на сторінці інтеграції (Write access → Enable): Brama ще раз відправляє до Google по дозвіл на зміни в Search Console, а далі власник позначає, які саме ресурси агент може змінювати. Усе непозначене лишається лише для читання – brama_gsc_list_sites показує це в колонці write_allowed. Кожна зміна – це пара «чернетка → застосування»: *_draft нічого не змінює й повертає підсумок із confirm_token, агент показує підсумок, і лише після твоєї згоди викликає brama_gsc_apply_change. Токен одноразовий і живе 5 хвилин; дозвіл на запис і список ресурсів перевіряються ще раз у момент застосування.

brama_gsc_sitemaps_submit_draft

Підготувати подання (або повторне подання) sitemap для ресурсу. Повторне подання просить Google завантажити sitemap знову – типово після міграції теми чи зміни URL. Чернетка каже, новий це sitemap чи вже поданий (і з якими лічильниками).Параметри: site_url (required), sitemap_url (required) – повна публічна URL під ресурсом.

brama_gsc_sitemaps_delete_draft

Підготувати видалення поданого sitemap. Сторінки з індексу не зникають – Search Console лише перестає відстежувати цей sitemap. Чернетка показує поточні submitted / indexed.Параметри: site_url (required), sitemap_url (required) – як у brama_gsc_list_sitemaps.

brama_gsc_sites_add_draft

Підготувати додавання ресурсу до Search Console підключеного Google-акаунта. Ресурс додається непідтвердженим – право власності далі підтверджується в Search Console (DNS-запис для domain property, HTML-файл чи тег для URL-префікса). Щоб агент міг додати ресурс, якого ще немає, власник вписує його URL у список на сторінці інтеграції.Параметри: site_url (required) – sc-domain:example.com або URL-префікс із косою рискою в кінці.

brama_gsc_sites_delete_draft

Підготувати видалення ресурсу з Search Console цього акаунта. Інші власники ресурс зберігають, індекс Google не змінюється, але цей акаунт втрачає дані Search Console по ресурсу до повторного додавання й підтвердження.Параметри: site_url (required).

brama_gsc_apply_change

Застосувати зміну, підготовлену будь-яким brama_gsc_*_draft. Агент викликає її лише після твоєї явної згоди в розмові. Одноразова.Параметри: confirm_token (required) – з чернетки.

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

  • “Які пошукові запити приносили найбільше кліків минулого місяця?”
  • “Покажи топ-сторінки за органічним пошуком за квартал.”
  • “Чи проіндексована сторінка example.com/pricing?”
  • “Mobile vs desktop ефективність за останні 28 днів.”
  • “Розділи запити на брендові й небрендові за вересень.”
  • “Що приносить трафік із Discover за останні 2 тижні?”
  • “Витягни всі запити за квартал – посторінково.”
  • “Перевір індексацію всіх сторінок колекцій після зміни теми.”
  • “Що всередині sitemap-індексу й де помилки?”
  • “Подай sitemap.xml ще раз після міграції теми.”
  • “Чи здорові мої sitemap-и – скільки URL проіндексовано?”

Безпека

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

Питання

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