# Yandex Direct Mcp

> MCP server for Yandex Direct API: campaigns, ads, keywords, bids, reports. Click.ru proxy or direct OAuth with sandbox. Docs in Russian.

- **Type:** MCP server
- **Install:** `agentstack add mcp-ai-hub-open-yandex-direct-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ai-hub-open](https://agentstack.voostack.com/s/ai-hub-open)
- **Installs:** 0
- **Category:** [Security](https://agentstack.voostack.com/c/security)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [ai-hub-open](https://github.com/ai-hub-open)
- **Source:** https://github.com/ai-hub-open/yandex-direct-mcp

## Install

```sh
agentstack add mcp-ai-hub-open-yandex-direct-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Yandex Direct MCP

MCP-сервер для [Yandex Direct JSON API v5](https://yandex.ru/dev/direct/) на Bun + TypeScript.

49 инструментов: кампании (включая ЕПК, стратегии торгов и цели Метрики), группы объявлений, объявления (текстовые и комбинаторные), расширения (быстрые ссылки, уточнения), изображения, ставки, корректировки ставок, ключевые фразы, отчёты, справочники.

## Требования

- [Bun](https://bun.sh) 1.1+

## Установка

```bash
git clone https://github.com/ai-hub-open/yandex-direct-mcp.git
cd yandex-direct-mcp
bun install
```

## Настройка

Скопируйте `.env.example` в `.env` и заполните **один из двух режимов** (переменные окружения имеют приоритет над `.env`):

**A. Прямой режим — свой OAuth-токен Яндекс.Директа:**

```bash
YANDEX_DIRECT_TOKEN=y0__...
YANDEX_DIRECT_SANDBOX=false   # true — песочница
```

По умолчанию используется версия API **v501** (обязательна для ЕПК); переключить можно через `YANDEX_DIRECT_API_VERSION=v5`.

**B. Через прокси [Click.ru](https://click.ru) — OAuth-токен Яндекса не нужен:**

```bash
CLICK_RU_PROXY=true
CLICK_RU_TOKEN=
CLICK_RU_CLIENT_LOGIN=
CLICK_RU_USER_ID=   # только при работе из мастер-аккаунта
```

Токен создаётся в профиле `https://click.ru/userinfo.html` → поле «API Token» → «Создать». Аккаунт Яндекс.Директа должен быть подключён в Click.ru. Справка: `https://help.click.ru/81`, `https://api.click.ru/V0/docs/`.

> Прокси Click.ru работает только с продакшн-API Яндекса (песочница недоступна).

## Запуск

```bash
bun run src/index.ts                                  # stdio — для локальных MCP-клиентов
MCP_AUTH_TOKEN= bun run src/index.ts --http   # HTTP-сервер на :3000
```

В HTTP-режиме `MCP_AUTH_TOKEN` обязателен — см. [HTTP-режим](#http-режим).

## Тесты

Обязательный гейт перед изменениями — мок-тесты (тела запросов к API, без сети) и тесты HTTP-транспорта (авторизация, CORS):

```bash
bun run test
```

E2E-прогон на песочнице (создаёт и удаляет тестовые кампании; нужны `YANDEX_DIRECT_TOKEN` и `YANDEX_DIRECT_SANDBOX=true`):

```bash
bun run test:sandbox
```

**Ограничения песочницы Яндекса** (в проде их нет; часть лечится пересозданием песочницы в кабинете — Инструменты → Настройки API → Песочница). E2E помечает такие шаги как «пропуск», а не как ошибку:

- `adgroups.add` возвращает ID, но группа не появляется в `adgroups.get`, а `ads.add` отвечает «Группа объявлений не найдена» — заливка объявлений в песочнице непроверяема;
- `bidmodifiers.add` возвращает ID, но `bidmodifiers.get` всегда пуст при любом фильтре;
- сервис `sitelinks` отвечает «Сервис временно недоступен».

## Подключение к Claude Code

`.mcp.json` в корне вашего проекта (см. также `.mcp.json.example`):

```json
{
  "mcpServers": {
    "yandex-direct": {
      "command": "bun",
      "args": ["run", "/абсолютный/путь/к/yandex-direct-mcp/src/index.ts"],
      "env": {
        "CLICK_RU_PROXY": "true",
        "CLICK_RU_TOKEN": "",
        "CLICK_RU_CLIENT_LOGIN": ""
      }
    }
  }
}
```

Для прямого режима в `env` вместо `CLICK_RU_*` укажите `YANDEX_DIRECT_TOKEN`.

**📋 Инструкция для AI-агента** — скопируйте и передайте своему агенту (Claude Code / Codex), подставив ключи:

> Установи и подключи MCP-сервер «Yandex Direct»: склонируй `https://github.com/ai-hub-open/yandex-direct-mcp.git`, проверь Bun (`bun --version`, если нет — установи с https://bun.sh), выполни `bun install` в корне репозитория. Зарегистрируй локальный stdio-MCP: команда `bun`, аргументы `run /src/index.ts`, переменные окружения — мои ключи: `CLICK_RU_PROXY=true`, `CLICK_RU_TOKEN=`, `CLICK_RU_CLIENT_LOGIN=` (или `YANDEX_DIRECT_TOKEN=` для прямого режима). Проверь `tools/list` и сообщи результат.

## HTTP-режим

```bash
MCP_TRANSPORT=http MCP_PORT=3000 MCP_AUTH_TOKEN= bun run src/index.ts
```

**`MCP_AUTH_TOKEN` обязателен**: без него сервер не стартует, потому что открытый эндпоинт даёт полный доступ к рекламному кабинету. Запросы должны нести `Authorization: Bearer `. Если сервер закрыт reverse-proxy или слушает только localhost, запуск без авторизации подтверждается явно: `MCP_ALLOW_ANONYMOUS=true`.

Переменные: `MCP_PORT` (3000), `MCP_HOST` (0.0.0.0), `MCP_AUTH_TOKEN`, `MCP_ALLOW_ANONYMOUS`, `MCP_ALLOWED_ORIGIN`. CORS-заголовки по умолчанию **не выдаются** (MCP-клиенты ходят не из браузера) — разрешите конкретный источник через `MCP_ALLOWED_ORIGIN`, если он действительно нужен.

| Метод + путь | Назначение |
|---|---|
| `POST /mcp` | JSON-RPC 2.0 запрос (или батч) |
| `GET /healthz` | health check |
| `GET /mcp/tools` | список инструментов (отладка) |

**Multi-tenant:** креды можно передавать заголовками на каждый запрос (перекрывают `.env`) — один инстанс обслуживает несколько клиентов:

```
X-Yandex-Token:               X-Click-Ru-Token: 
X-Yandex-Sandbox: true|false         X-Click-Ru-User-Id: 
X-Yandex-Api-Version: v501|v5        X-Client-Login: 
                                     X-Click-Ru-Base-Url: 
```

В режиме Click.ru по HTTP обязательны все три заголовка. Сервер можно запустить без кред в `.env` — тогда каждый запрос обязан нести заголовки.

**⚠️ Безопасность:** при публикации в сеть держите `MCP_AUTH_TOKEN` заданным и закройте порт за reverse-proxy с TLS. Запуск с `MCP_ALLOW_ANONYMOUS=true` на `MCP_HOST=0.0.0.0` открывает кабинет всем, кто дотянется до порта.

## Docker

```bash
cp .env.example .env   # заполните ключи и MCP_AUTH_TOKEN
docker compose up -d --build
curl http://localhost:3000/healthz
```

## Инструменты (49)

- **Campaigns**: get / add / update / delete / suspend / resume — текстовые кампании и ЕПК (единая перформанс-кампания), стратегии торгов с недельным бюджетом, счётчики Метрики и приоритетные цели
- **AdGroups**: get / add / update / delete — включая группы ЕПК (UnifiedAdGroup)
- **Ads**: get / add / add_responsive (комбинаторное объявление ЕПК) / update (текстовые и комбинаторные) / delete / suspend / resume / moderate
- **AdImages**: add (с кропом) / get
- **Sitelinks**: add / get / delete — наборы быстрых ссылок
- **AdExtensions**: add / get / delete — уточнения
- **BidModifiers**: devices / regional / retargeting / demographics / set / delete / get — корректировки ставок на запись и чтение
- **Keywords**: get / add / update / delete / suspend / resume
- **KeywordBids**: set / get — ставки по фразам и данные аукциона (объёмы трафика, цены)
- **Reports**: campaign / ad / search_queries / custom (произвольный тип и набор столбцов)
- **Dictionaries**: regions / currencies / interests / all

### Предпросмотр записи (dry-run)

Любой инструмент, меняющий кабинет, принимает `dry_run: true` — вернёт тело запроса, которое ушло бы в API, и **ничего не изменит**. Валидация параметров при этом выполняется полностью, так что предпросмотр ловит ошибки до записи:

```json
{ "name": "yandex_direct_campaigns_add", "arguments": { "name": "Тест", "start_date": "2026-08-01", "dry_run": true } }
```

### Что осознанно вне этого моста

Мост покрывает **только API Яндекс.Директа**. Смежные задачи живут в других контурах и сюда не встраиваются:

- **Вордстат** (подбор семантики, частотность, прогноз бюджета) — отдельный API Яндекса, не Директ. Остаётся за скиллом или отдельным MCP.
- **Метрика как сервис** (создание целей, чтение статистики, сегменты) — отдельный API Метрики. Мост Директа привязывает цель по готовому ID (`counter_ids`, `priority_goals`, `goal_id` в стратегиях) — на этом граница.

Причина: «одно подключение к Яндексу = Директ + Метрика + Вордстат» — это уровень пакета или прокси (например Click.ru), а не одного сервера. Смешение трёх API в одном мосте увеличивает связность и зону отказа.

## Лицензия

[Apache License 2.0](LICENSE)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ai-hub-open](https://github.com/ai-hub-open)
- **Source:** [ai-hub-open/yandex-direct-mcp](https://github.com/ai-hub-open/yandex-direct-mcp)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-ai-hub-open-yandex-direct-mcp
- Seller: https://agentstack.voostack.com/s/ai-hub-open
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.