Google Ads MCP Server

Этот репозиторий содержит исходный код для запуска MCP сервера, который взаимодействует с Google Ads API.

Инструменты

Сервер использует Google Ads API для предоставления нескольких Инструментов и Ресурсов для использования с LLM и AI-агентами.

Доступные инструменты

• search: Получает информацию об аккаунте Google Ads.

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

• list_accessible_customers: Возвращает идентификаторы клиентов, напрямую доступных пользователю, проходящему аутентификацию при вызове.

Настройка и пространства имен инструментов

Сервер Google Ads MCP использует tools_config.yaml, чтобы позволить вам выборочно включать или отключать отдельные инструменты или категории инструментов (пространства имен) и настраивать их префиксы пространств имен.

Файл tools_config.yaml по умолчанию со всеми включенными инструментами поставляется вместе с пакетом, поэтому сервер работает "из коробки" без дополнительной настройки. Чтобы настроить вашу установку, сервер разрешает конфигурацию в следующем порядке:

1. Явный путь, заданный через переменную окружения GOOGLE_ADS_MCP_TOOLS_CONFIG.

2. Файл tools_config.yaml в текущей рабочей директории.

3. Файл tools_config.yaml по умолчанию, поставляемый с пакетом.

Если явно запрошенный файл конфигурации (через переменную окружения) отсутствует или любой разрешенный файл недействителен, сервер выдает ошибку и не запускается.

Пример конфигурации:

namespaces:
  # Option 1: Enable category 'customers' with default prefix -> "customers_list_accessible_customers"
  customers: true

  # Option 2: Enable category 'search' with a custom prefix -> "query_search"
  search: "query"

  # Option 3: Fine-grained control over tools in a category
  metadata:
    enabled: true
    prefix: "metadata"
    enabled_tools:
      - get_resource_metadata: true

Доступные ресурсы

• discovery-document: Получает документ обнаружения Google Ads API. Предоставляет документ обнаружения для последней версии Google Ads API, который описывает поверхность API, включая ресурсы, методы и схемы. Хост-LLM должны обращаться к этому ресурсу, чтобы понять структуру Google Ads API и обнаружить доступные функции.

• metrics: Получает информацию о метриках, доступных для отчетности в Google Ads API.

• segments: Получает информацию о сегментах, доступных для отчетности в Google Ads API.

• release-notes: Получает примечания к выпуску для последней версии Google Ads API.

Related MCP server: gads

Примечания

1. MCP-сервер предоставит ваши данные агенту или LLM, к которому вы его подключаете.

2. Если у вас возникли технические проблемы, пожалуйста, используйте GitHub issue tracker.

3. Чтобы помочь нам собирать данные об использовании, вы заметите, что к вашим вызовам API был добавлен дополнительный заголовок: эти данные используются для улучшения продукта.

Инструкции по настройке

Настройка включает следующие шаги:

1. Настройка Python.

2. Настройка токена разработчика.

3. Включение API в вашем проекте.

4. Настройка учетных данных.

5. Настройка вашего MCP-клиента.

Настройка Python

Установите pipx.

Настройка токена разработчика

Следуйте инструкциям по Получению токена разработчика.

Ваш токен разработчика должен иметь как минимум доступ уровня Explorer для запросов к производственным аккаунтам. Новые токены могут быть автоматически повышены до доступа Explorer; если нет, вы можете подать заявку через API Center. См. документацию по уровням доступа для подробностей.

Если вы видите ошибку "The developer token is only approved for use with test accounts", ваш токен еще не имеет доступа к производственным аккаунтам. См. документацию по уровням доступа о том, как запросить необходимый уровень доступа.

Включение API в вашем проекте

Следуйте инструкциям, чтобы включить следующие API в вашем проекте Google Cloud:

• Google Ads API

Настройка учетных данных

Вариант 1: Использование FastMCP OAuth Proxy

Сервер поддерживает функцию OAuth proxy от FastMCP для динамической аутентификации пользователей. Это полезно при запуске сервера в качестве веб-сервиса.

Чтобы включить его, установите следующие переменные окружения:

• GOOGLE_ADS_MCP_OAUTH_CLIENT_ID: Идентификатор клиента OAuth 2.0 Google Cloud.

• GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET: Секрет клиента OAuth 2.0 Google Cloud.

• GOOGLE_ADS_MCP_BASE_URL: (Необязательно) Базовый URL, по которому доступен сервер (по умолчанию http://localhost:8080).

• GOOGLE_ADS_MCP_JWT_SIGNING_KEY: (Необязательно) Секретный ключ для подписи токенов FastMCP JWT на нескольких экземплярах сервера или развертываниях.

• GOOGLE_ADS_MCP_STORAGE_TYPE: (Необязательно) Серверная часть хранилища для состояния OAuth (filetree, redis, firestore или memory).

• GOOGLE_ADS_MCP_STORAGE_PATH: (Необязательно) Путь к каталогу для постоянного хранилища filetree.

• GOOGLE_ADS_MCP_STORAGE_REDIS_URL: (Необязательно) URL Redis для постоянного хранилища redis.

• GOOGLE_ADS_MCP_STORAGE_FIRESTORE_PROJECT: (Необязательно) Проект Google Cloud для постоянного хранилища firestore. По умолчанию используется проект, полученный из Application Default Credentials. Его установка выбирает серверную часть firestore, даже если GOOGLE_ADS_MCP_STORAGE_TYPE не задан.

• GOOGLE_ADS_MCP_STORAGE_FIRESTORE_DATABASE: (Необязательно) Имя базы данных Firestore для постоянного хранилища firestore. По умолчанию (default).

• GOOGLE_ADS_MCP_STORAGE_ENCRYPTION_KEY: (Необязательно) Ключ шифрования для хранимых токенов OAuth.

• GOOGLE_ADS_MCP_STORAGE_DISABLE_ENCRYPTION: (Необязательно) Установите значение true, чтобы отключить шифрование токенов.

Для серверных частей redis и firestore требуется установить их библиотеку хранения вместе с сервером: pip install py-key-value-aio[redis] и pip install google-ads-mcp[firestore] соответственно.

После включения этой функции вы сможете проходить аутентификацию в API через ваш MCP-клиент.

Когда эти переменные установлены, сервер автоматически переключается на транспорт streamable-http (SSE/HTTP) вместо stdio.

Вам нужно будет запустить сервер как отдельный процесс и настроить ваш MCP-клиент для подключения к конечной точке SSE (например, http://localhost:8080/mcp).

Вариант 2: Настройка учетных данных с использованием Application Default Credentials

Настройте ваши Application Default Credentials (ADC). Убедитесь, что учетные данные принадлежат пользователю, имеющему доступ к вашим аккаунтам или свойствам Google Ads.

Учетные данные должны включать область Google Ads API:

https://www.googleapis.com/auth/adwords

Ознакомьтесь с Управлением OAuth-клиентами о том, как создать OAuth-клиент.

Вот несколько примеров команд gcloud, которые могут быть вам полезны:

• Настройка ADC с использованием учетных данных пользователя и OAuth-клиента для настольного или веб-приложения после загрузки JSON-файла клиента в YOUR_CLIENT_JSON_FILE.

  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

• Настройка ADC с использованием олицетворения сервисного аккаунта.

  gcloud auth application-default login \
    --impersonate-service-account=SERVICE_ACCOUNT_EMAIL \
    --scopes=https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform

Когда команда gcloud auth application-default завершится, скопируйте расположение файла PATH_TO_CREDENTIALS_JSON, выведенное на консоль в следующем сообщении. Он понадобится вам на следующем шаге!

Credentials saved to file: [PATH_TO_CREDENTIALS_JSON]

Вариант 3: Настройка учетных данных с использованием клиентской библиотеки Python Google Ads API.

Следуйте инструкциям по настройке и конфигурированию клиентской библиотеки Python Google Ads API.

Если вы уже сделали это и у вас есть рабочий файл google-ads.yaml, вы можете повторно использовать этот файл!

В файле utils.py измените метод get_googleads_client() для использования метода load_from_storage().

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

Добавьте сервер в конфигурацию вашего MCP-клиента. Ниже приведены примеры для популярных клиентов.

Antigravity CLI / Antigravity Code Assist

1. Установите Antigravity CLI или Antigravity Code Assist.

2. Настройте ваш сервер. Обратитесь к документации по адресу https://antigravity.google/docs/mcp для получения подробной информации о настройке MCP-серверов.

• Вариант 1: Использование FastMCP OAuth Proxy (Streamable HTTP)

  Вы можете запустить сервер как отдельный процесс и настроить ваш MCP-клиент для подключения к конечной точке SSE (например, http://localhost:8080/mcp). Это также позволяет использовать функцию OAuth proxy от FastMCP для динамической аутентификации пользователей.

  {
    "mcpServers": {
      "google-ads-mcp": {
        "httpUrl":"http://localhost:8080/mcp",
        "env": {
          "GOOGLE_PROJECT_ID": "YOUR_PROJECT_ID",
          "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN"                        
        }
      }
    }
  }

• Вариант 2: метод Application Default Credentials

  Замените PATH_TO_CREDENTIALS_JSON на путь, который вы скопировали на предыдущем шаге.

  Мы также рекомендуем добавить атрибут GOOGLE_CLOUD_PROJECT в объект env. Замените YOUR_PROJECT_ID в следующем примере на идентификатор проекта вашего проекта Google Cloud.

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

• Вариант 3: метод клиентской библиотеки Python

  {
    "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_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN"
        }
      }
    }
  }

Идентификатор клиента для входа

Если ваш доступ к аккаунту клиента осуществляется через аккаунт менеджера, вам нужно будет добавить идентификатор клиента аккаунта менеджера в файл настроек.

См. здесь для подробностей.

Итоговый файл будет выглядеть так:

{
  "mcpServers": {
    "google-ads-mcp": {
      "command": "pipx",
      "args": [
        "run",
        "--spec",
        "git+https://github.com/googleads/google-ads-mcp.git",
        "google-ads-mcp"
      ],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON",
        "GOOGLE_PROJECT_ID": "YOUR_PROJECT_ID",
        "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "YOUR_MANAGER_CUSTOMER_ID"
      }
    }
  }
}

Другие MCP-клиенты (Claude Code, Cursor, VS Code и т.д.)

Формат блока mcpServers одинаков для всех MCP-клиентов. Добавьте конфигурацию, показанную выше, в соответствующий файл настроек для вашего клиента (например, ~/.claude/settings.json для Claude Code, .cursor/mcp.json для Cursor, .vscode/mcp.json для VS Code с Copilot).

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

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

Обратите внимание, что это поддерживает аутентификацию только с парой идентификатора клиента OAuth и секрета клиента через прокси OAuth (Вариант #1 выше).

Предварительные требования

1. Проект Google Cloud.

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

   gcloud config set project YOUR_PROJECT_ID

Шаг 1: Сборка и отправка Docker-образа

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

1. Создайте репозиторий в Artifact Registry:

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

2. Соберите и отправьте образ:

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

   Замените YOUR_PROJECT_ID на идентификатор вашего проекта Google Cloud.

Шаг 2: Развертывание на Google Cloud Run

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

• GOOGLE_PROJECT_ID: Идентификатор вашего проекта Google Cloud.

• GOOGLE_ADS_DEVELOPER_TOKEN: Токен разработчика, который должен использовать MCP-сервер (см. выше).

• GOOGLE_ADS_MCP_OAUTH_CLIENT_ID: Идентификатор клиента OAuth, который должен использовать MCP-сервер.

• GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET: Секрет клиента OAuth, который должен использовать MCP-сервер.

• GOOGLE_ADS_MCP_BASE_URL: Базовый URL, по которому доступен ваш MCP-сервер: он будет автоматически назначен Google Cloud Run после первого развертывания. Вы можете обновить переменные окружения после развертывания.

• GOOGLE_ADS_MCP_JWT_SIGNING_KEY: (Рекомендуется для production) Постоянный ключ подписи JWT для экземпляров Cloud Run.

• GOOGLE_ADS_MCP_STORAGE_TYPE: (Рекомендуется для production) Бэкенд хранилища для сохранения токенов OAuth между экземплярами. Установите значение firestore для использования Firestore через учетные данные приложения по умолчанию (без VPC-коннектора) или redis вместе с GOOGLE_ADS_MCP_STORAGE_REDIS_URL.

  Использование firestore требует трех вещей: собрать образ с дополнительной зависимостью (изменить Dockerfile на uv pip install --system .[firestore]), создать базу данных Firestore в проекте (она не создается автоматически) и предоставить сервисному аккаунту Cloud Run роль roles/datastore.user. Обратите внимание, что записи не удаляются автоматически: хранилище фильтрует просроченные записи при чтении, но никогда не удаляет их, а expires_at записывается как строка, поэтому политика TTL Firestore также не может их собрать. Планируйте периодическую очистку для долгоживущих развертываний. Redis сам удаляет просроченные записи.

• FASTMCP_HOST: Установите значение 0.0.0.0, чтобы FastMCP принимал соединения со всех IP-адресов.

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_DEVELOPER_TOKEN=YOUR_DEVELOPER_TOKEN,GOOGLE_ADS_MCP_OAUTH_CLIENT_ID=YOUR_CLIENT_ID,GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET=YOUR_CLIENT_SECRET,GOOGLE_ADS_MCP_BASE_URL=YOUR_BASE_URL,GOOGLE_ADS_MCP_JWT_SIGNING_KEY=YOUR_JWT_SIGNING_KEY,GOOGLE_ADS_MCP_STORAGE_TYPE=firestore,FASTMCP_HOST=0.0.0.0"

Шаг 3: Настройка MCP-клиента

После развертывания обновите конфигурацию вашего MCP-клиента (см. документацию по адресу https://antigravity.google/docs/mcp), чтобы использовать URL Cloud Run.

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

Попробуйте

Запустите ваш MCP-клиент. Вы должны увидеть google-ads-mcp в списке доступных серверов.

Вот несколько примеров запросов для начала:

• Спросите, что умеет сервер:

  what can the 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?

Примечание об идентификаторе клиента

Ваш агент будет запрашивать идентификатор клиента для большинства запросов. Если вы переключаетесь между несколькими клиентами, возможно, проще указывать идентификатор клиента в запросе.

How many active campaigns do I have for customer id 1234567890

Участие в разработке

Приветствуются любые вклады! См. Руководство по участию.