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

Развертывание в 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 в разделе API и сервисы > Окно запроса доступа OAuth > Доступ к данным (Добавить или удалить области действия).
    • Если для статуса публикации окна запроса доступа 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 выполняет запросы на языке запросов Google Рекламы (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