MCP-сервер Google Ads: підключіть Claude і закрийте доступ

MCP-сервер Google Ads — це відкрита програма від Google, яка дає змогу ШІ-асистентові, наприклад Claude, надсилати запити до вашого рекламного акаунта через Google Ads API. Поточний випуск працює лише на читання і має три інструменти. Щоб підключити його, потрібні проєкт Google Cloud із доступом щонайменше Explorer, облікові дані OAuth і один блок конфігурації у вашому асистенті. Спершу закрийте доступ: входьте через окремий акаунт Google з роллю «Лише перегляд» (Read only), бо API використовує один і той самий дозвіл і для читання, і для запису.

Асистент, підключений через MCP, — один із кількох способів дозволити програмам працювати у вашому рекламному акаунті. Інші — автоматичні правила, скрипти й сам API. Наш посібник з автоматизації Google Ads порівнює їх. У цій статті — про офіційний сервер, два види рівнів доступу, які його обмежують, налаштування в Claude Desktop і Claude Code та обмеження, на які натрапляють у перший тиждень.

Що офіційний сервер може і чого не може

Model Context Protocol — це відкритий стандарт для підключення ШІ-застосунків до зовнішніх систем, за документацією MCP. MCP-сервер — це програма на іншому боці цього з’єднання. Вона пропонує інструменти. Модель, що стоїть за асистентом, сама вирішує, коли їх викликати, а результати потрапляють у контекстне вікно моделі.

Сервер Google стоїть між асистентом і Google Ads API. Його посібник з інтеграції для розробників описує сервер як програму на Python, що працює на вашому комп’ютері або в Cloud Run як вебсервіс. Вхід відбувається через OAuth 2.0 або сервісний акаунт. Поточний випуск лише читає: за словами Google, він не може змінювати ставки, ставити кампанії на паузу чи створювати нові об’єкти. Код відкритий на GitHub за ліцензією Apache 2.0.

Інструмент search сам пише запит GAQL, і цей запит завжди починається з SELECT. Сервер лишається в режимі читання, бо кожен інструмент викликає лише методи API для читання: жоден не надсилає зміни. Сервер також пропонує чотири довідкові ресурси: документ виявлення API, список метрик, список сегментів і найновіші примітки до випуску.

Два рядки в README сервера важливі, перш ніж щось підключати. Дані вашого акаунта потрапляють до того асистента й тієї моделі, до яких ви підключаєте сервер. А ще сервер додає до викликів API додатковий заголовок, щоб Google міг збирати дані про використання.

Два види рівнів доступу визначають, до чого має доступ асистент

Google вживає слова «рівень доступу» для двох не пов’язаних речей. Одна обмежує, що користувач, який увійшов, може робити в рекламному акаунті. Друга обмежує, скільки запитів може виконати ваш проєкт Google Cloud. Обидві треба налаштувати правильно.

Рівні доступу користувача: що може змінити той, хто увійшов

Google Ads API запозичує модель доступу з Google Ads. За Understand the Google Ads access model, API використовує однакові області дозволів OAuth і для операцій лише читання, і для операцій читання та запису. Він дотримується ролей користувачів, які підтримує Google Ads. У коді самого сервера сказано те саме: окремої області лише для читання Google не публікує, тож обмеження на читання випливає з інструментів, які пропонує сервер.

Наслідок такий: офіційний сервер не писатиме, але облікові дані, які ви для нього створюєте, можуть писати в будь-якому іншому інструменті, що їх використає. Обмеження змін, яке Google забезпечує сам, — це роль користувача, що увійшов. API розпізнає чотири рівні доступу користувача, або ролі, перелічені в довіднику AccessRole:

Ролі, надані на керуючому обліковому записі, передаються всім акаунтам, прив’язаним до нього. Скажімо, ви входите з акаунтом Google, що має доступ «Стандартний» або «Адміністратор» на керуючому обліковому записі агентства. Тоді асистент має доступ до всіх клієнтських акаунтів під ним із цією роллю.

Рівні доступу до API: скільки запитів може виконати ваш проєкт Cloud

Google вивів токени розробника з обігу 9 вересня 2026 року, як сказано на сторінці Developer token. Рівні доступу до API тепер закріплені за проєктом Google Cloud, що володіє вашим клієнтом OAuth або сервісним акаунтом. Якщо запит усе ще містить токен розробника, API його ігнорує.

README репозиторію досі описує крок із токеном розробника й позначає його як необов’язковий. У посібнику Google з інтеграції сказано, що остання версія сервера його вже не потребує.

Ліміти для кожного рівня — зі сторінки Google Access levels and permissible use:

Explorer — найнижчий рівень, що може опитувати робочий акаунт, тобто такий, який показує реальну рекламу. Заявку подають на сторінці Google Ads API Overview у Google Cloud Console, і Google може підвищити проєкт автоматично. Перш ніж подавати заявку на Basic, ваш проєкт Cloud має пройти верифікацію бренду.

Кожен запит Search або SearchStream вважається однією операцією, скільки б рядків він не повернув (API limits and quotas). Google рахує добу як останні 24 години в будь-який момент. Тож 2 880 операцій на добу — це два запити на хвилину цілодобово.

Людині, яка ставить запитання, цього вистачає з великим запасом. Асистент, який виконує окремий запит для кожної кампанії чи кожного дня, може вичерпати ліміт.

Як підключити Claude до Google Ads крок за кроком

Ці кроки ставлять замок на перше місце, щоб облікові дані ніколи не належали акаунту Google з правами адміністратора.

1. Створіть акаунт Google, від імені якого діятиме асистент. Використайте окрему адресу, наприклад reports@your-domain. Попросіть адміністратора акаунта надати їй роль «Лише перегляд» у Google Ads (як надати роль). Перевірка: новий акаунт прийняв запрошення, а в списку користувачів біля його адреси стоїть «Лише перегляд».

2. Налаштуйте проєкт Google Cloud. Увімкніть у ньому Google Ads API, відкрийте сторінку Google Ads API Overview і подайте заявку на Explorer, якщо проєкт досі показує Test. Перевірка: на сторінці вказано Explorer, Basic або Standard.

3. Створіть облікові дані OAuth і увійдіть як акаунт із роллю «Лише перегляд». Створіть клієнт OAuth для комп’ютера або вебзастосунку, завантажте його файл JSON, а тоді виконайте команду з README. Коли відкриється браузер, виберіть акаунт із роллю «Лише перегляд», а не власний адміністраторський акаунт.

   gcloud auth application-default login \
     --scopes https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform \
     --client-id-file=YOUR_CLIENT_JSON_FILE

   Перевірка: команда виводить шлях, куди збережено файл облікових даних. Ставтеся до цього файлу як до пароля: той, хто його має, діє від імені цього користувача.

4. Установіть pipx і додайте сервер до свого асистента. Це блок із посібника Google з інтеграції:

   {
     "mcpServers": {
       "google-ads-mcp": {
         "command": "pipx",
         "args": ["run", "--spec", "git+https://github.com/googleads/google-ads-mcp.git", "google-ads-mcp"],
         "env": {
           "GOOGLE_PROJECT_ID": "YOUR_PROJECT_ID",
           "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/credentials.json"
         }
       }
     }
   }

   • Claude Desktop: відкрийте «Settings» у меню Claude, перейдіть до «Developer» і виберіть «Edit Config». Відкриється файл claude_desktop_config.json. Вставте блок, збережіть, потім закрийте й перезапустіть застосунок (Connect to local MCP servers).
   • Claude Code: додайте той самий сервер із командного рядка (Connect Claude Code to tools via MCP). Залиште --transport stdio між змінними й назвою сервера, інакше CLI прочитає назву як ще одну змінну.

   claude mcp add --env GOOGLE_PROJECT_ID=YOUR_PROJECT_ID GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json \
     --transport stdio google-ads-mcp \
     -- pipx run --spec git+https://github.com/googleads/google-ads-mcp.git google-ads-mcp

   Якщо ви потрапляєте в акаунт через керуючий обліковий запис, додайте GOOGLE_ADS_LOGIN_CUSTOMER_ID з ідентифікатором керуючого акаунта. За README, той самий блок mcpServers працює в Cursor і VS Code.

5. Виконайте першу перевірку. Запитайте: «До яких клієнтів я маю доступ?» Перевірка: відповідь — список ідентифікаторів акаунтів. Якщо ви бачите помилку CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION, проєкт усе ще має доступ Test.

Що закрити до першого справжнього запиту

Два з цих замків найважливіші, щойно ви додаєте сторонній сервер з інструментами запису: обережність зі сторонніми текстами й тестовий акаунт. Запобіжники для такого випадку описано в нашій статті про ШІ-агентів, що змінюють ваш акаунт.

Обмеження, на які ви натрапите в перший тиждень

Відповіді, що не вміщуються. Інструмент search повертає всі рядки, якщо модель не задасть ліміт. Claude Code попереджає, коли вивід інструмента перевищує 10 000 токенів. Понад 25 000 токенів за замовчуванням він зберігає результат у файл і передає Claude шлях до нього.

Приклад на вигаданому магазині, числа не клієнтські.

У магазині посуду 3 000 товарів, і 1 200 із них цього місяця отримали покази. Звіт з одним рядком на товар на день за 30 днів може повернути до 36 000 рядків. Порівняно з лімітом у 25 000 токенів це менш ніж один токен на рядок. Просіть підсумки за кампаніями або 50 найдорожчих товарів, а не всі рядки.

Квота. На рівні Explorer усе, що використовує проєкт Cloud, зокрема асистент, ділить 2 880 операцій на добу.

Історія змін. Ресурс change_event охоплює лише останні 30 днів, а кожен запит потребує LIMIT не більш як 10 000 рядків (Change Event). Для кожної зміни він показує старі й нові значення та те, чи прийшла зміна через API, чи через вебінтерфейс. Він також називає користувача, коли його показує історія змін.

Поля, що означають не те, що здається. Три приклади з довідників полів Google для API:

• Гроші вимірюються в мікро: мільйон мікро дорівнює одній одиниці валюти акаунта (довідник campaign_budget).
• metrics.all_conversions рахує всі конверсії, зокрема дії, які ви виключили зі стовпця «Конверсії» (довідник metrics).
• Втрачена частка показів у пошуку через бюджет обмежується значенням 0,9: усе, що вище, API повідомляє як 0,9001.

Наша стаття про ШІ для аналізу Google Ads показує, як модель хибно трактує такі поля, і дає запити, що не дозволяють їй вигадувати цифри. Наш посібник про GAQL для товарної звітності містить готові запити для товарів у Shopping і Performance Max.

Спершу читати, кожен запис підтверджувати: правила з нашого дизайн-брифу MCP

У квітні 2026 року ми склали дизайн-бриф власного MCP-сервера Google Ads. Це внутрішня чернетка, а не опис продукту, що вже працює. Її правила підходять для будь-якого налаштування:

1. Читання йде першим. Перша фаза — лише читання, а запис — окрема, пізніша фаза.
2. Інструмент довільного запиту приймає лише SELECT. Сирий GAQL може лише читати дані.
3. Кожен запис потребує явного підтвердження. Інструменти, які задають лейбли й ставки товарів, чекають на «так», а інструмент ставок показує попереднє значення, перш ніж застосувати нове.
4. Зміни структури проходять через людину. Інструмент створює CSV для Google Ads Editor, який людина переглядає й імпортує.
5. Дизайн враховує великі відповіді й квоту. Кожен інструмент має параметр ліміту, пагінацію й режим підсумку. Кешування та пакетні запити захищають добову квоту.

Портал дотримується правил щодо читання, і сервер вам запускати не треба. Ви можете увійти окремим акаунтом Google з роллю «Лише перегляд», тож гарантія лежить на боці Google (як портал читає ваш акаунт).

Портал і власноруч створене з’єднання відрізняються двома речами: підтримкою й історією. MCP-з’єднання ви будуєте й підтримуєте самі, а дворічна історія магазину в чат не вміщується (порівняння порталу з ChatGPT). Під час першого підключення портал просить у Google до двох років історії товарів. Відтоді він зберігає власну копію записів про зміни, які API віддає лише за 30 днів.

Хочете гарантію, а не обіцянку? Увійдіть через акаунт Google з роллю «Лише перегляд» у вашому акаунті. Портал повністю успадковує дозволи того, хто увійшов, тож не може нічого змінити навіть теоретично: Google відхилить спробу — у користувача немає прав.

Увійти через Google Ads →

Три перші запити й як перевірити відповіді

1. «До яких клієнтів я маю доступ?» Порівняйте ідентифікатори зі списком акаунтів у Google Ads. Зайвий ідентифікатор означає, що акаунт Google має доступ до більшої кількості акаунтів, ніж ви планували.
2. «Використай get_resource_metadata для shopping_performance_view і перелічи поля для витрат, кліків і цінності конверсій.» Власні інструкції сервера кажуть моделі шукати поля, а не вгадувати. Цей запит показує, чи так вона й робить.
3. «Покажи витрати, кліки й цінність конверсій за кампаніями за минулий місяць, 20 найдорожчих за витратами.» Відкрийте в Google Ads розділ «Кампанії» за ті самі дати й порівняйте підсумки. Якщо вони відрізняються, спершу перевірте дати, потім мікро, потім чи не використала модель all_conversions.

Використовуйте цифри асистента в рішеннях, щойно всі три відповіді збігаються з тим, що ви бачите в Google Ads.

Поширені запитання

Чи може MCP-сервер Google Ads змінювати мої кампанії?

Ні. Google описує поточний випуск як такий, що лише читає, а його інструменти викликають тільки методи API для читання. Інші MCP-сервери для Google Ads можуть містити інструменти запису. Перевіряйте перелік інструментів кожного сервера і ставтеся до їхніх власних позначок «лише читання» як до тверджень, а не гарантій.

Чи працює він з асистентами, окрім Claude?

Так, з будь-яким асистентом, що підтримує MCP. README подає налаштування для Google Antigravity, OpenAI Codex, Claude Code, Cursor і VS Code.

Чи потрібен мені ще токен розробника?

Ні. З 9 вересня 2026 року рівень доступу до API належить проєкту Google Cloud. Якщо запит усе ще містить токен розробника, API його ігнорує.

Джерела

• Google Ads MCP server: Developer integration guide (англійською) — поточний випуск лише для читання, Python, stdio або Cloud Run, OAuth 2.0 або сервісний акаунт, три інструменти, токен розробника більше не потрібен, блок конфігурації. Перевірено 02.10.2026.
• googleads/google-ads-mcp on GitHub (англійською) — інструменти й ресурси, примітки про доступ до даних і заголовок використання, tools_config.yaml, ізоляція облікових даних, Claude Code та інші клієнти, команда gcloud; вихідний код інструмента search. Перевірено 02.10.2026.
• Understand the Google Ads access model (англійською) — однакові області дозволів OAuth для операцій лише читання та читання й запису; API дотримується ролей користувачів Google Ads; ролі передаються через керуючі облікові записи. Перевірено 02.10.2026.
• AccessRole (англійською) — що дозволяють ролі Admin, Standard, Read only і Email only. Перевірено 02.10.2026.
• Developer token (англійською) — токени розробника виведено з обігу 9 вересня 2026 року; рівні доступу належать проєкту Cloud; верифікація бренду для Basic; помилка доступу Test. Перевірено 02.10.2026.
• Access levels and permissible use (англійською) — ліміти рівнів Test, Explorer, Basic і Standard; як подати заявку на Explorer; ковзна 24-годинна доба. Перевірено 02.10.2026.
• API limits and quotas (англійською) — один запит Search або SearchStream вважається однією операцією. Перевірено 02.10.2026.
• Test accounts (англійською) — тестові акаунти не показують рекламу й потребують окремої тестової ієрархії керуючих акаунтів. Перевірено 02.10.2026.
• Change Event (англійською) — вікно 30 днів, LIMIT 10 000 рядків, старі й нові значення, користувач і тип клієнта. Перевірено 02.10.2026.
• Metrics reference і campaign_budget reference (англійською) — all_conversions, межа 0,9 для втраченої частки показів у пошуку через бюджет, мікро. Перевірено 02.10.2026.
• What is the Model Context Protocol (MCP)? і Tools in the MCP specification (англійською) — визначення MCP; людина в циклі; анотації інструментів недовірені, якщо сервер не є довіреним. Перевірено 02.10.2026.
• Connect to local MCP servers (англійською) — файл конфігурації Claude Desktop і файли журналів сервера. Перевірено 02.10.2026.
• Connect Claude Code to tools via MCP і Claude Code security (англійською) — claude mcp add, області встановлення, ліміти виводу 10 000 і 25 000 токенів, prompt injection. Перевірено 02.10.2026.
• Дизайн-бриф MCP-сервера GetProfit, квітень 2026 (внутрішня чернетка) — спершу читання, сирі запити лише з SELECT, підтверджені записи, CSV для Editor для структури, ліміти й пагінація.