yandex-direct-mcp

MCP-сервер для получения отчётов по поисковым запросам из Яндекс Директ.

Интегрируется с MCP SuperAssistant (Chrome/Firefox) и любым другим MCP-клиентом.

Возможности

Инструмент get_search_query_report возвращает отчёт «Поисковые запросы» с полями:

| Поле API | Колонка в отчёте | |---|---| | Query | Поисковый запрос | | CampaignName | Название кампании | | CampaignId | № Кампании | | AdGroupName | Название группы | | AdGroupId | № Группы | | CriterionType | Тип условия показа | | Criterion | Ключевая фраза | | MatchType | Тип соответствия | | QueryTarget | Категория запроса | | Cost | Расход, ₽ | | Impressions | Показы | | Clicks | Клики | | Ctr | CTR, % | | Conversions* | Конверсии | | ConversionRate* | CR, % | | CostPerConversion* | CPA, ₽ | | AvgPageviews** | Глубина просмотра | | BounceRate** | Отказы, % | | AvgImpressionPosition | Ср. позиция показа |

* требуют передачи goal_ids
** требуют подключённой Яндекс Метрики

Быстрый старт

1. Установить зависимости и собрать

npm install
npm run build

2. Получить OAuth-токен Яндекс Директ

1. Создайте приложение на oauth.yandex.ru с правом direct:api
2. Получите токен и сохраните его в переменной окружения:

# .env (локально)
YANDEX_DIRECT_TOKEN=y0_AgAAAA...

Или передавайте токен напрямую в параметре access_token при каждом вызове инструмента.

3. Подключить к MCP SuperAssistant

Создайте config.json (скопируйте config.example.json) с путём к собранному серверу:

{
  "mcpServers": {
    "yandex-direct": {
      "command": "node",
      "args": ["C:/путь/до/yandex-direct-mcp/dist/index.js"],
      "env": {
        "YANDEX_DIRECT_TOKEN": "y0_AgAAAA..."
      }
    }
  }
}

Запустите прокси-сервер:

npx -y @srbhptl39/mcp-superassistant-proxy@latest --config ./config.json --outputTransport sse

В расширении MCP SuperAssistant введите URL: http://localhost:3006/sse и нажмите Connect.

Альтернатива — запуск через npx (после публикации в npm)

# config.json с командой npx:
{
  "mcpServers": {
    "yandex-direct": {
      "command": "npx",
      "args": ["-y", "yandex-direct-mcp"],
      "env": { "YANDEX_DIRECT_TOKEN": "y0_AgAAAA..." }
    }
  }
}

Параметры инструмента

| Параметр | Тип | Обязателен | Описание | |---|---|---|---| | access_token | string | нет* | OAuth-токен Директа | | client_login | string | нет | Логин клиента (для агентских аккаунтов) | | date_from | string | да | Начало периода YYYY-MM-DD | | date_to | string | да | Конец периода YYYY-MM-DD | | campaign_ids | number[] | нет | Фильтр по ID кампаний | | goal_ids | number[] | нет | ID целей Метрики для Конверсий/CR/CPA | | include_metrica | boolean | нет | Включить поля Метрики (по умолчанию true) |

* если не передан — берётся из YANDEX_DIRECT_TOKEN

Пример запроса к AI

После подключения сервера введите в чат:

Покажи отчёт по поисковым запросам за последние 7 дней (2026-04-20 — 2026-04-27),
кампании 12345678 и 87654321.

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

src/
  index.ts          — MCP-сервер (stdio transport)
  yandex-direct.ts  — клиент Яндекс Директ Reports API v5
dist/               — скомпилированный JS (после npm run build)
config.example.json — пример конфига для mcp-superassistant-proxy
.env.example        — пример переменных окружения

Публикация в npm

# Убедитесь, что name в package.json уникален
npm login
npm publish

Лицензия

MIT