ya-direct-mcp

MCP-сервер для Яндекс.Директ API v5. Управление кампаниями, группами, объявлениями, ключевыми фразами и выгрузка статистики — через инструменты, доступные Claude.

Транспорт — Streamable HTTP. Рассчитан на деплой в Railway. Поддерживаются текстово-графические кампании (TEXT_CAMPAIGN).

1. Что внутри

Кампании: list_campaigns, get_campaign, create_campaign, update_campaign, suspend_campaign, resume_campaign, archive_campaign, delete_campaign

Группы: list_adgroups, create_adgroup, update_adgroup, delete_adgroup

Объявления: list_ads, create_ad, update_ad, moderate_ad, suspend_ad, resume_ad, delete_ad

Ключевые фразы: list_keywords, add_keywords, update_keyword_bids, suspend_keywords, resume_keywords, delete_keywords

Статистика: get_report, get_account_balance

Все инструменты принимают необязательный параметр client_login. Если он не передан, используется логин из переменной окружения YD_LOGIN. Это позволяет обслуживать несколько рекламодателей одним сервером.

Related MCP server: google-ads-mcp

2. Переменные окружения

Сгенерировать MCP_SECRET:

python -c "import secrets; print(secrets.token_urlsafe(32))"

3. Деплой в Railway

1. New Project → Deploy from GitHub repo → выбрать ya-direct-mcp.

2. Variables → добавить YD_TOKEN, YD_LOGIN, MCP_SECRET. Переменную PORT не задавать — Railway проставит сам.

3. Settings → Networking → Generate Domain. Появится адрес вида ya-direct-mcp-production.up.railway.app.

4. Дождаться сборки. Проверить готовность:

curl https://ВАШ-ДОМЕН.up.railway.app/health
# ожидается: ok

Nixpacks определит Python по requirements.txt и запустит команду из railway.json.

4. Подключение к Claude

Адрес MCP-эндпоинта включает секрет:

https://ВАШ-ДОМЕН.up.railway.app/mcp/ВАШ_MCP_SECRET

Настройки → Connectors → Add custom connector → вставить этот URL → Add.

Затем в чате: кнопка + → Connectors → включить yandex-direct.

Сервер принимает авторизацию двумя способами:

• секрет в пути URL (как выше) — работает всегда;

• заголовок Authorization: Bearer <MCP_SECRET> — если в вашем интерфейсе доступна секция «Request headers» (функция в бете и раскатывается постепенно).

Достаточно любого из двух.

5. Локальный запуск

python -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -r requirements.txt

cp .env.example .env           # заполнить своими значениями
export $(grep -v '^#' .env | xargs)

python src/server.py
# → http://localhost:8000/mcp/<MCP_SECRET>

6. Безопасность

• Эндпоинт открыт в интернет. Единственная защита — MCP_SECRET. Утечка секрета = полный доступ к рекламному аккаунту, включая удаление кампаний.

• Секрет хранится только в переменных Railway. В репозиторий не коммитится.

• При компрометации: сменить MCP_SECRET в Railway (сервис перезапустится сам), затем пересоздать коннектор в Claude с новым URL.

• delete_campaign защищён предохранителем: требует точного совпадения имени кампании с переданным значением confirm_name. Остальные delete_* предохранителя не имеют — удаление необратимо.

• OAuth-токен Директа живёт только в окружении сервера. Claude его не видит.

7. Денежные значения

API Директа принимает деньги в микроединицах: 1 ₽ = 1 000 000.

Инструменты этого сервера конвертируют автоматически — в daily_budget_amount, bid и context_bid передавайте рубли.

Исключение: объекты стратегий (strategy_search, strategy_network) передаются в API как есть, поэтому суммы внутри них указывайте в микроединицах.

8. Пример: смена целевой цены конверсии

strategy_search  = {"BiddingStrategyType": "SERVING_OFF"}
strategy_network = {
  "BiddingStrategyType": "NETWORK_DEFAULT",
  "NetworkDefault": {
    "BiddingStrategyType": "AVERAGE_CPA",
    "AverageCpa": {
      "AverageCpa": 1000000000,      // 1000 ₽ в микроединицах
      "GoalId": 503496561
    }
  }
}

При смене стратегии нужно передавать оба поля — API требует объект BiddingStrategy целиком.

9. Расход баллов

Лимит суточных баллов приходит в заголовке units каждого ответа и пишется в логи. Чтение расходует единицы баллов, отчёты — десятки. При суточном лимите ~996 000 упереться в потолок практически невозможно.