Google Ads MCP — управление Google Ads и GA4 через Claude

Сервер MCP (Model Context Protocol) для работы с Google Ads и Google Analytics 4 напрямую из Claude Code или Claude Desktop. Позволяет анализировать кампании, управлять ставками и ключевыми словами, создавать объявления и получать отчёты GA4 — всё с подтверждением каждого изменения.

Автор: Gabriel Urrutia (@gabogabucho). Проект вдохновлён AdLoop от kLOsk, но полностью переписан для Claude с поддержкой Windows, macOS и Linux.

Возможности

• Анализ эффективности кампаний, объявлений и ключевых слов
• Просмотр поисковых запросов и предложение минус-слов
• Приостановка / активация кампаний, групп и объявлений
• Создание адаптивных поисковых объявлений (RSA)
• Добавление минус-слов
• Выполнение произвольных GAQL-запросов
• Отчёты и данные о пользователях в реальном времени из GA4

Все операции записи работают по схеме preview → confirm: сначала показывается, что будет изменено, затем требуется явное подтверждение.

Требования

• Python 3.11+
• uv — менеджер пакетов
• Аккаунт Google Ads с доступом к API
• Проект в Google Cloud с включёнными API

Установка

Windows (PowerShell)

git clone https://github.com/gabogabucho/google-ads-mcp.git
cd google-ads-mcp
powershell -ExecutionPolicy Bypass -File install.ps1

macOS / Linux (bash)

git clone https://github.com/gabogabucho/google-ads-mcp.git
cd google-ads-mcp
bash install.sh

Скрипты установки:

• Проверяют наличие Python, uv и git
• Создают виртуальное окружение и устанавливают зависимости
• Генерируют ~/.google-ads-mcp/config.yaml из примера
• Копируют навыки в ~/.claude/skills/
• Показывают точный фрагмент для настройки Claude Desktop

Настройка Google

1. Проект в Google Cloud

Перейдите в console.cloud.google.com → создайте проект и включите API:

• Google Ads API
• Google Analytics Data API
• Google Analytics Admin API

2. Учётные данные OAuth 2.0

APIs & Services → Credentials → Create → OAuth 2.0 Client ID

• Тип приложения: Desktop app
• Скачайте JSON и сохраните как ~/.google-ads-mcp/credentials.json

3. Developer Token Google Ads

В Google Ads: инструменты (шестерёнка) → API Center → скопируйте токен. Токен уровня TEST работает только с тестовыми аккаунтами.

4. Настройка config.yaml

Отредактируйте файл конфигурации:

• macOS/Linux: $EDITOR ~/.google-ads-mcp/config.yaml
• Windows: notepad %USERPROFILE%\.google-ads-mcp\config.yaml

Все поля описаны в config/config.yaml.example.

5. Первая аутентификация

При первом запуске python -m google_ads_mcp откроется браузер для входа в Google. Токен сохраняется в ~/.google-ads-mcp/token.json и обновляется автоматически.

Настройка Claude Desktop

Отредактируйте claude_desktop_config.json:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "google-ads": {
      "command": "ПУТЬ_К_PYTHON_ИЗ_VENV",
      "args": ["-m", "google_ads_mcp"],
      "env": {
        "GOOGLE_ADS_MCP_CONFIG": "ПУТЬ_К_CONFIG_YAML"
      }
    }
  }
}

Установщик покажет точные пути для вашей системы.

Настройка Claude Code

Добавьте глобально:

claude mcp add google-ads \
  --env GOOGLE_ADS_MCP_CONFIG=$HOME/.google-ads-mcp/config.yaml \
  -- python -m google_ads_mcp

Или создайте .mcp.json в корне проекта (см. config/mcp.json.example).

Доступные навыки (Skills)

После установки в Claude Code доступны команды:

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

Чтение — Google Ads

Чтение — GA4

Запись (preview → confirm)

Система безопасности

Все изменения проходят многоступенчатую проверку:

1. Пользователь запрашивает изменение
2. preview_*() — проверяет лимиты, генерирует план с коротким ID
3. Claude показывает предпросмотр и запрашивает подтверждение
4. apply_change(plan_id, dry_run=True) — сначала симуляция
5. apply_change(plan_id, dry_run=False) — только после явного OK

Активные защиты:

• Максимальный дневной бюджет (настраивается)
• Лимит на процент повышения ставок
• Список заблокированных операций
• Лог аудита в ~/.google-ads-mcp/audit.log
• Новые RSA создаются в статусе PAUSED

Структура проекта

google-ads-mcp/
├── src/google_ads_mcp/
│   ├── server.py      # FastMCP: определение всех инструментов
│   ├── ads.py         # Google Ads API (чтение и запись)
│   ├── ga4.py         # Google Analytics 4 API (только чтение)
│   ├── auth.py        # OAuth 2.0 с кэшированием токена
│   ├── config.py      # Загрузка config.yaml
│   └── safety.py      # Защиты, хранилище планов, лог аудита
├── skills/
│   ├── google-ads-analyze/SKILL.md
│   ├── google-ads-manage/SKILL.md
│   ├── google-ads-ga4/SKILL.md
│   └── google-ads-setup/SKILL.md
├── config/
│   ├── config.yaml.example
│   ├── claude-desktop-config.json.example
│   └── mcp.json.example
├── docs/troubleshooting.md
├── install.sh          # macOS / Linux
├── install.ps1         # Windows PowerShell
├── pyproject.toml
└── LICENSE             # MIT

Лицензия

MIT — подробнее в LICENSE.