MCP-сервер Google Рекламы: руководство по интеграции для разработчиков

Model Context Protocol (MCP) – это открытый стандарт, который позволяет большим языковым моделям (LLM) безопасно взаимодействовать с внешними данными и приложениями. Сервер MCP Google Рекламы – это стандартизированный мост к Google Ads API, который позволяет ИИ-агентам анализировать и получать данные кампаний с помощью естественного языка.

Ресурсы и поддержка сообщества

Технический обзор

Внедрив этот MCP-сервер, вы избавитесь от необходимости писать собственный связующий код для аутентификации Google Ads API, получения ресурсов и синтаксического анализа данных. Сервер предоставляет определенные инструменты, которые LLM может обнаруживать и вызывать автономно.

Основные характеристики

  • Протокол: MCP (Model Context Protocol).
  • Режим: Только чтение (текущая версия)
  • Язык: Python.
  • Транспорт: стандартный ввод/вывод (stdio) или потоковый HTTP (streamable-http / Cloud Run).
  • Аутентификация: OAuth 2.0 или сервисный аккаунт.

Как работает цикл взаимодействия

  1. Запрос. Пользователь отправляет запрос, например "Какова эффективность моей кампании на этой неделе?".
  2. Обнаружение. LLM проверяет доступные инструменты и определяет возможности google-ads-mcp.
  3. Выполнение. MCP-сервер выполняет базовую логику Python для запроса к Google Ads API.
  4. Внедрение контекста. Структурированные результаты возвращаются в окно контекста LLM.
  5. Ответ. LLM синтезирует данные в человекочитаемый ответ.

Начать

Чтобы настроить и использовать сервер MCP Google Рекламы, выполните следующие действия:

Требования

Перед настройкой убедитесь, что у вас есть следующие учетные данные из консоли Google Cloud:

Конфигурация

Чтобы интегрировать сервер в хост, совместимый с MCP, добавьте следующую запись в файл конфигурации MCP хоста, например settings.json, и укажите в GOOGLE_APPLICATION_CREDENTIALS путь к JSON-файлу ADC (или настройте ADC по умолчанию с помощью gcloud auth application-default login). Если вы получаете доступ к аккаунтам через управляющий аккаунт, вы также можете задать GOOGLE_ADS_LOGIN_CUSTOMER_ID. Точное местоположение и название файла конфигурации можно найти в документации хостинга.

{
  "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"
      }
    }
  }
}

Дополнительно: добавьте навыки и помощника разработчика

MCP-сервер Google Рекламы предоставляет вашему ИИ-клиенту доступ только для чтения к данным аккаунта в реальном времени. Чтобы помочь агенту создавать действительные запросы на языке запросов Google Рекламы (GAQL), диагностировать изменения эффективности аккаунта и генерировать код клиентской библиотеки, используйте MCP-сервер вместе со следующими инструментами:

  • Навыки агента Google Ads API. Портативные модули инструкций и рабочих процессов, связанных с Google Ads API, включая google-ads-api-mcp-setup, google-ads-api-account-diagnostics и google-ads-api-quickstart, которые учат агента эффективно использовать сервер MCP Google Рекламы с меньшими затратами токенов. Установите их с помощью одной команды (требуется Node.js) или ознакомьтесь с руководством по навыкам агента Google Ads API для Antigravity, Claude Code, Codex и Cursor:

    npx skills add google/skills/skills/ads

  • Google Ads API Developer Assistant. Модульный плагин для Google Antigravity и Claude Code, который позволяет проверять локальные схемы Protobuf, выполнять программную валидацию GAQL, генерировать код клиентской библиотеки (включая скрипты изменения) и устранять неполадки с офлайн-конверсиями. Подробнее о том, как работает Google Ads API Developer Assistant… Вы также можете ознакомиться с руководством по установке.

Развертывание в Google Cloud

Вместо локального хостинга MCP-сервера вы можете разместить его в Google Cloud Run или любой другой облачной инфраструктуре. Это полезно, если вы хотите использовать сервер для разных агентов или запустить его как веб-сервис.

Требования

  1. Проект Google Cloud.

  2. Установленный и аутентифицированный инструмент командной строки gcloud с настроенным активным проектом.

    gcloud config set project YOUR_PROJECT_ID

Как создать и отправить образ Docker

Вы можете использовать Cloud Build, чтобы создать образ и отправить его в Artifact Registry, не устанавливая Docker локально.

  1. Создайте хранилище в Artifact Registry:

    gcloud artifacts repositories create mcp-servers \
  --repository-format=docker --location=us-central1

  2. Перейдите в каталог проекта:

    cd <full path>/google-ads-mcp

  3. Создайте и отправьте образ:

    gcloud builds submit \
  --tag us-central1-docker.pkg.dev/YOUR_PROJECT_ID/mcp-servers/google-ads-mcp:latest .

    Обратите внимание, что этот шаг необходимо выполнять каждый раз, когда вы хотите обновить развернутый сервер до последней версии.

Развернуть в Google Cloud Run

Убедитесь, что вы задали необходимые переменные среды:

  • GOOGLE_PROJECT_ID – идентификатор проекта Google Cloud с нужными уровнями доступа к API.
  • GOOGLE_ADS_MCP_OAUTH_CLIENT_ID – идентификатор клиента OAuth 2.0 (настроенный как веб-приложение в вашем облачном проекте Google Cloud) для аутентификации OAuth на уровне приложения. Убедитесь, что:
    • Вы добавили подходящие авторизованные URI перенаправления для всех ИИ-клиентов, которые планируете подключить (например, https://claude.ai/api/mcp/auth_callback, https://chatgpt.com/connector_platform_oauth_redirect или https://antigravity.google/oauth-callback).
    • Вы добавили область действия https://www.googleapis.com/auth/adwords в окно запроса доступа OAuth в разделе APIs & Services (API и сервисы) > OAuth consent screen (Окно запроса доступа OAuth) > Data Access (Доступ к данным) (Add or remove scopes (Добавить или удалить области действия)).
    • Если для статуса публикации окна запроса доступа OAuth установлено значение Тестирование (по умолчанию), вы добавили аккаунты Google, подключающиеся к серверу MCP, в качестве тестовых пользователей в разделе API и сервисы > Окно запроса доступа OAuth > Аудитория (Тестовые пользователи > + Добавить пользователей).
  • GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET – секретный код клиента OAuth, соответствующий идентификатору клиента OAuth.
  • GOOGLE_ADS_MCP_BASE_URL – общедоступный базовый URL, по которому можно получить доступ к серверу MCP (например, https://google-ads-mcp-xyz-uc.a.run.app). Поскольку Google Cloud Run генерирует этот URL во время первоначального развертывания, сначала выполните развертывание без этой переменной, а затем обновите сервис.
  • FASTMCP_HOST: задайте значение 0.0.0.0, чтобы разрешить FastMCP принимать подключения со всех IP-адресов.

Разверните сервис в Google Cloud Run:

gcloud run deploy google-ads-mcp \
  --image us-central1-docker.pkg.dev/YOUR_PROJECT_ID/mcp-servers/google-ads-mcp:latest \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars="GOOGLE_PROJECT_ID=YOUR_PROJECT_ID,GOOGLE_ADS_MCP_OAUTH_CLIENT_ID=YOUR_CLIENT_ID,GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET=YOUR_CLIENT_SECRET,FASTMCP_HOST=0.0.0.0"

После того как Cloud Run завершит развертывание, получите назначенный URL сервиса и обновите сервис с помощью переменной среды GOOGLE_ADS_MCP_BASE_URL:

gcloud run services update google-ads-mcp \
  --region us-central1 \
  --update-env-vars="GOOGLE_ADS_MCP_BASE_URL=https://your-cloud-run-url.a.run.app"

Модель аутентификации и безопасности

Развертывание с помощью --allow-unauthenticated отключает проверку IAM на уровне инфраструктуры Cloud Run (roles/run.invoker), чтобы внешние клиенты ИИ могли подключаться без токенов сервисных аккаунтов Google Cloud. Вместо этого аутентификация делегируется прикладному уровню:

  • Если указаны GOOGLE_ADS_MCP_OAUTH_CLIENT_ID и GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET, MCP-сервер применяет Google OAuth 2.0 ко всем входящим запросам, отправляя неаутентифицированным вызывающим абонентам ответ HTTP 401. Все запросы инструментов выполняются строго в рамках идентификационных данных OAuth аутентифицированного вызывающего абонента.
  • Если не указать --allow-unauthenticated, будет применяться IAM инфраструктуры Cloud Run, требующий от вызывающих объектов передавать токены идентификации OIDC Google Cloud с каждым запросом. Поскольку стандартные ИИ-клиенты (такие как Claude и ChatGPT) выполняют аутентификацию с помощью OAuth конечного пользователя, а не токенов идентификации Google Cloud IAM, для прямых подключений с этих платформ требуется --allow-unauthenticated с OAuth на уровне приложения.

Настройте MCP-клиент

После развертывания настройте клиент MCP, указав URL Cloud Run. Поскольку серверу требуется аутентификация OAuth 2.0, клиент должен поддерживать поток MCP OAuth или предоставить авторизованный токен на предъявителя:

  • Клиенты с поддержкой OAuth. Для клиентов, поддерживающих обнаружение MCP OAuth (например, Antigravity), подключение к конечной точке вызывает окно аутентификации для входа с аккаунтом Google и предоставления области действия https://www.googleapis.com/auth/adwords (в консоли Google Cloud она указана как .../auth/adwords).
  • Сторонние ИИ-платформы (Claude, ChatGPT). В настройках коннектора или интеграции клиента добавьте собственный коннектор, указывающий на URL Cloud Run с путем /mcp (например, https://your-cloud-run-url.a.run.app/mcp), выберите аутентификацию OAuth 2.0 (используя собственный идентификатор клиента OAuth и секретный код клиента) и убедитесь, что URI обратного вызова клиента добавлен в авторизованные URI перенаправления клиента OAuth. Участники пилотного проекта по размещению конечных точек, добавленные в белый список, могут также ознакомиться с руководством по настройке размещенной конечной точки MCP.
  • Клиенты без поддержки OAuth. Клиенты, которые не поддерживают потоки HTTP OAuth, получат ответ HTTP 401 Unauthorized. Для таких инструментов используйте локальную конфигурацию stdio.

Пример конфигурации для клиента с поддержкой OAuth (например, ~/.gemini/settings.json):

{
  "mcpServers": {
    "google-ads-mcp": {
      "httpUrl": "https://your-cloud-run-url.a.run.app/mcp"
    }
  }
}

Основные возможности (инструменты)

Сервер предоставляет инструменты для поиска аккаунтов и создания отчетов об эффективности:

  • list_accessible_customers – возвращает список идентификаторов клиентов Google Рекламы и названий аккаунтов, доступных аутентифицированному пользователю.
  • search выполняет запросы GAQL для получения показателей ресурсов, бюджетов и статусов.

  • get_resource_metadata: извлекает метаданные о типе ресурса Google Ads API, например "campaign".

    Это позволяет понять структуру данных и узнать, какие поля доступны для запросов.

Примеры запросов

Спросите, что может сделать сервер.

What can the google-ads-mcp server do?

Вопросы о клиентах

What customers do I have access to?

Вопросы о кампаниях

How many active campaigns do I have?
How is my campaign performance this week?
Give me a report of the top spending campaigns split by device category over the
last 7 days for account 1234567890

Дальнейшие действия