Google Ads MCP

Google Ads MCP — это локальный MCP-сервер и плагин Codex только для чтения, с приоритетом безопасности, предназначенные для просмотра аккаунтов Google Ads. Версия 0.1.0 предоставляет ограниченный набор инструментов для инвентаризации, отчетности, метаданных, истории изменений и безопасного GAQL. Он не содержит возможностей записи, загрузки, планирования, удаления, оптимизации или размещенного транспорта.

Публичный дистрибутив Python называется google-ads-operator-mcp. Название продукта и имя команды остаются Google Ads MCP и google-ads-mcp.

Границы безопасности

• Каждый запрос в рамках аккаунта указывает и профиль, и идентификатор клиента.

• Учетные данные Google хранятся в Application Default Credentials или в явном файле google-ads.yaml, доступном только владельцу, за пределами репозитория.

• accounts.json может содержать только имя переменной окружения для токена разработчика, но никогда сам токен.

• allowWrites должно быть false; любое другое значение отклоняется.

• Только GoogleAdsService, CustomerService и GoogleAdsFieldService создаются производственным адаптером.

• Инструмент получает нормализованные строки, но никогда — клиент Google или необработанную оболочку ответа.

• В режиме MCP stdout зарезервирован для JSON-RPC. Диагностика и очищенные коды ошибок отправляются в stderr.

Перед подключением производственного аккаунта прочтите SECURITY.md, PRIVACY.md и модель угроз.

Related MCP server: appstoreconnect-codex-mcp

Требования

• Python 3.11, 3.12 или 3.13

• uv

• Доступ к Google Ads API с токеном разработчика

• ADC или отдельно хранимый google-ads.yaml, доступный только владельцу

Руководствуйтесь официальными рекомендациями Google по токену разработчика, конфигурации Python-клиента и Application Default Credentials.

Локальная настройка

uv sync --frozen --all-groups
uv run --frozen google-ads-mcp version
uv run --frozen google-ads-mcp config init

После публичного релиза автономный CLI также можно установить с помощью uv tool install google-ads-operator-mcp==0.1.0. Для финальной приемочной проверки чистого плагина используйте архив плагина из релиза, а не копию из дерева исходников.

Отредактируйте ~/.config/google-ads-mcp/accounts.json, замените публичные идентификаторы аккаунтов и восстановите права доступа только для владельца:

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

chmod 600 ~/.config/google-ads-mcp/accounts.json
gcloud auth application-default login
uv run --frozen google-ads-mcp config validate
uv run --frozen google-ads-mcp auth doctor --profile production-read-only

Не вставляйте токен разработчика, OAuth refresh token, client secret, ADC JSON или содержимое YAML-файлов в этот репозиторий, issue, запись терминала или чат.

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

Приоритет конфигурации: сначала --config, затем GOOGLE_ADS_MCP_CONFIG, затем ~/.config/google-ads-mcp/accounts.json.

{
  "profiles": [
    {
      "name": "production-read-only",
      "loginCustomerId": "1234567890",
      "defaultCustomerId": "0987654321",
      "auth": {
        "type": "adc",
        "developerTokenEnv": "GOOGLE_ADS_DEVELOPER_TOKEN"
      },
      "allowWrites": false
    }
  ]
}

Для существующего YAML-файла клиента Google используйте {"type":"googleAdsYaml","path":"/absolute/owner-only/google-ads.yaml"}. Относительные пути и символические ссылки отклоняются. Сервер никогда не ищет учетные данные в формате YAML в рабочем каталоге или репозитории.

CLI

google-ads-mcp version
google-ads-mcp config init
google-ads-mcp config validate
google-ads-mcp auth doctor --profile <name>
google-ads-mcp accounts discover --profile <name>
google-ads-mcp serve --stdio

Инструменты MCP

Фиксированный набор возможностей v0.1:

auth_check                customers_list
customer_get              customer_hierarchy
account_health            campaigns_query
campaign_inventory        resource_metadata
reports_catalog           report_run
change_events_query       gaql_validate
gaql_search

Типизированные списки возвращают не более 200 элементов на страницу. Одна операция чтения Google ограничена 1 000 нормализованных строк. Пятиминутные курсоры привязаны к профилю и конкретному запросу; на профиль допускается не более 20 активных курсоров. Безопасный GAQL не использует курсор и требует один SELECT без комментариев, нечувствительный ресурс и LIMIT 1..1000.

Параметры, семантику подтверждений и поведение отчетов см. в docs/tools.md.

Плагин Codex

Корень репозитория является корнем плагина. .mcp.json вызывает ./bin/google-ads-mcp-launcher, который через stdio запускает только замороженное окружение uv. Неявный навык google-ads-operator обрабатывает все строки аккаунтов как ненадежные данные и никогда не предлагает недоступные инструменты изменения.

Репозиторий намеренно не создает и не изменяет запись в личном маркетплейсе. Установка из релизного архива проверяется отдельно на этапе приемки.

Проверка

uv run --frozen ruff check .
uv run --frozen pyright
uv run --frozen pytest
uv run --frozen python scripts/validate_read_only.py
uv run --frozen python scripts/validate_gaql_templates.py
uv run --frozen python ~/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py .
uv run --frozen python ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/google-ads-operator

Автоматизированная проверка не является приемкой на реальном аккаунте. Контрольные точки для тестового аккаунта и производственного режима только для чтения, описанные в docs/acceptance.md, остаются обязательными до выхода v0.1.0.

Лицензия

Apache-2.0. Google Ads — товарный знак Google LLC. Этот проект независим и не одобрен компанией Google.