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. Это позволяет обслуживать несколько рекламодателей одним сервером.

---

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

Переменная	Обязательна	Назначение
YD_TOKEN	да	OAuth-токен Яндекс.Директа
YD_LOGIN	да	Логин рекламодателя по умолчанию
MCP_SECRET	да	Собственный секрет сервера для защиты эндпоинта. Не токен Яндекса
PORT	нет	Railway подставляет автоматически
LOG_LEVEL	нет	INFO по умолчанию
YD_REPORT_TIMEOUT	нет	Максимум ожидания отчёта, сек. По умолчанию 120

Сгенерировать 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 упереться в потолок практически невозможно.