ads-mcp-server

Локальный MCP-сервер, предоставляющий данные о производительности Google Ads и Meta Marketing, настройки кампаний и историю изменений для Claude (Cowork) для рабочих процессов с ежедневными дашбордами в реальном времени.

Что он делает

Три инструмента, зарегистрированные в MCP:

Архитектура: получение необработанных данных ad×day один раз в час для каждой платформы, кэширование в parquet, вычисление всех агрегаций в pandas. Никаких API-запросов при каждом разбиении (breakdown).

Related MCP server: Google Ads MCP Server

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

• macOS / Linux

• Python 3.13 (рекомендуется через pyenv)

• Менеджер пакетов uv: brew install uv

• Доступ к Google Ads API — см. начало работы с Google Ads API

• Доступ к Meta Marketing API — см. начало работы с Marketing API

Ссылки для настройки учетных данных

Установка

cd ~/marketing-ds/ads-mcp-server
uv sync --extra dev

uv создает .venv/ и устанавливает все зависимости, зафиксированные в pyproject.toml.

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

Два варианта:

Вариант А — указать на существующий .env (рекомендуется, если у вас уже есть ключи в ~/marketing-ds/decision_science/.env):

export ADS_MCP_ENV_FILE=/Users/jmacaggi/marketing-ds/decision_science/.env

Вариант Б — локальный .env:

cp .env.example .env
# fill in the blanks

Обязательные ключи перечислены в .env.example с комментариями, объясняющими каждый из них.

Запуск

Локально для тестирования:

uv run ads-mcp-server

Сервер общается по MCP через stdio — Cowork (или любой другой MCP-клиент) запускает его по требованию.

Подключение к Claude (Cowork)

Добавьте этот блок в ~/.claude/claude_desktop_config.json (создайте файл, если он отсутствует):

{
  "mcpServers": {
    "ads": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/jmacaggi/marketing-ds/ads-mcp-server",
        "run",
        "ads-mcp-server"
      ],
      "env": {
        "ADS_MCP_ENV_FILE": "/Users/jmacaggi/marketing-ds/decision_science/.env"
      }
    }
  }
}

Перезапустите Claude/Cowork. Инструменты get_google_ads_report, get_meta_ads_report, get_campaign_settings должны появиться.

Фоновый демон не требуется — Cowork запускает/останавливает процесс для каждой сессии.

Ежедневный предварительный прогрев (рекомендуется для живого дашборда)

Правило валидности кэша: кэш считается свежим, если он содержит дату вчерашнего дня. Обновляется раз в день. Первый запрос пользователя за день инициирует обновление — а получение данных за 56 дней для крупного аккаунта может занять 1-3 минуты.

Чтобы избежать этого ожидания, запланируйте предварительный прогрев на 6 утра через macOS launchd:

# Install
cp /Users/jmacaggi/marketing-ds/ads-mcp-server/launchd/com.jmacaggi.adsmcp.prewarm.plist \
   ~/Library/LaunchAgents/

launchctl load ~/Library/LaunchAgents/com.jmacaggi.adsmcp.prewarm.plist

# Verify it's scheduled
launchctl list | grep adsmcp

# Trigger immediately (test)
launchctl start com.jmacaggi.adsmcp.prewarm

# Logs
tail -f ~/marketing-ds/ads-mcp-server/logs/prewarm.stdout.log
tail -f ~/marketing-ds/ads-mcp-server/logs/$(date +%Y-%m-%d).log

Что он делает каждое утро в 6:00:

1. Получает данные производительности Google Ads за 56 дней, настройки, change_event за 29 дней → кэш

2. (Meta в настоящее время отключена — см. "Статус Meta" ниже)

3. Записывает метку обновления cache/google_lastrefresh.txt = сегодня

К тому времени, как вы откроете Cowork, данные Google будут актуальными. Вызовы инструментов будут возвращать результат менее чем за 1 секунду.

Для удаления:

launchctl unload ~/Library/LaunchAgents/com.jmacaggi.adsmcp.prewarm.plist
rm ~/Library/LaunchAgents/com.jmacaggi.adsmcp.prewarm.plist

Статус Meta (по состоянию на 2026-05-07)

Инструменты Meta (get_meta_ads_report, get_campaign_settings(platform="meta"|"both")) структурно завершены, но еще не проверены в сквозном режиме.

Что работает:

• Получение данных о производительности разбито на 7-дневные окна (позволяет избежать ошибки Service temporarily unavailable / subcode 1504044 "result too large")

• Данные на уровне объявлений разделены: level=campaign для 56-дневных рядов, level=ad только для вчерашнего дня (позволяет избежать 5-минутной пагинации)

• Получение AdSet фильтруется по effective_status IN [ACTIVE, PAUSED] (позволяет избежать пагинации тысяч архивированных групп объявлений)

Что нас блокировало:

• После первого большого порционного получения данных о производительности, получение AdSet достигло почасового лимита Meta (code 17, subcode 2446079: "User request limit reached"). Время ожидания обычно составляет 10-60 минут.

Для повторного тестирования завтра утром (после сброса квоты):

# Remove --skip-meta from the launchd plist to enable Meta in pre-warm
sed -i '' '/<string>--skip-meta<\/string>/d' \
   ~/Library/LaunchAgents/com.jmacaggi.adsmcp.prewarm.plist
launchctl unload ~/Library/LaunchAgents/com.jmacaggi.adsmcp.prewarm.plist
launchctl load ~/Library/LaunchAgents/com.jmacaggi.adsmcp.prewarm.plist

# Or run manually
ADS_MCP_ENV_FILE=/Users/jmacaggi/marketing-ds/decision_science/.env \
   uv run python scripts/prewarm.py

Если Meta продолжит ограничивать скорость, возможные запасные варианты (еще не реализованы):

• Асинхронный запуск отчетов (async=True) для получения данных о производительности

• Более строгий фильтр effective_status (только ACTIVE, исключить приостановленные)

Если вы предпочитаете долго работающий фоновый процесс (необязательно, не требуется для Cowork): используйте nohup uv run ads-mcp-server > /tmp/ads-mcp.log 2>&1 & или plist для launchd.

Дополнительно: переопределение через CSV (в обход API)

Google Ads UI позволяет экспортировать отчеты в CSV без ограничений квоты API. Поместите CSV в cache/external/, чтобы переопределить получение данных через API:

cache/external/google_2026-05-07.csv
cache/external/meta_2026-05-07.csv

Если соответствующий CSV существует И он новее, чем кэш parquet, сервер загрузит его вместо вызова API. В ответе будет установлено metadata.data_source = "csv_override", чтобы Cowork знал об этом.

Схема столбцов CSV должна соответствовать parquet (см. src/ads_mcp_server/google_ads.py и meta_ads.py для имен столбцов: date, campaign_id, campaign_name, ad_id, ad_name, spend, impressions, clicks, conversions, ...).

Тестирование

uv run pytest -v

Все тесты основаны на моках — никаких сетевых вызовов. Покрывают:

• classify_campaign (Брендовые/Небрендовые/Другое)

• diagnose (5-состояний классификатора)

• Выбор 8 недель по тем же дням недели (выбирает правильные 8 дат)

• Дельта WoW + деление на ноль

• Фильтр actions[] для Meta

• Сравнение снимков (snapshot diff), включая нулевые старые значения и очистку

• Отсутствие учетных данных возвращает чистую ошибку (без исключения)

Логи

Каждый вызов API и ошибка записываются в logs/YYYY-MM-DD.log (один файл в день).

Устранение неполадок

• Ошибка установки google-ads: убедитесь, что Python 3.13 (uv python pin 3.13) и pip install grpcio работают в вашей системе. На Apple Silicon: arch -arm64 uv sync.

• Истек срок действия токена Meta: пересоздайте токен системного пользователя в "Настройках компании"; долгоживущие токены действуют 60 дней.

• Инструмент не появляется в Cowork: проверьте ~/Library/Logs/Claude/mcp*.log на наличие ошибок запуска. Убедитесь, что uv находится в PATH для графического процесса (возможно, потребуется полный путь: which uv).

• Устаревший кэш: удалите cache/*.parquet, чтобы принудительно выполнить свежее получение данных.

Карта файлов

src/ads_mcp_server/
  server.py        # MCP entry + tool handlers
  config.py        # env loading, validates creds
  google_ads.py    # 3 GAQL queries: perf, settings, change_event
  meta_ads.py      # Insights + AdSet pull
  snapshots.py     # Meta snapshot diff (Meta has no reliable change API)
  cache.py         # parquet + CSV override
  aggregate.py     # all pandas math
  classify.py      # Brand/NB/Other
  diagnose.py      # 5-state diagnosis
  date_ranges.py   # window resolution + 8wk DoW
  retry.py         # exponential backoff
  logging_setup.py # daily file logs
  schema.py        # response shape constants