Яндекс.Метрика + Директ — MCP Server

MCP-сервер для работы с данными Яндекс.Метрики и Яндекс.Директа прямо из Claude.

Подключается к Claude Desktop, Claude Code и Cowork. После подключения Claude умеет сам запрашивать нужные данные — достаточно написать запрос на естественном языке.

Покажи трафик за последние 30 дней
Какие кампании Директа потратили больше всего в этом месяце?
Сравни поиск и РСЯ по конверсиям за последний месяц
Топ-20 ключевых фраз по расходу за неделю

Возможности

Яндекс.Метрика — 7 инструментов:

Сводка трафика, источники, топ страниц
Цели и конверсии
Аудитория по устройствам и городам
Активность сегодня по часам
Сравнение двух периодов

Яндекс.Директ — 12 инструментов:

Список кампаний, бюджеты, остаток Units API
Эффективность: клики, показы, CTR, CPC, конверсии, ROI
Топ ключевых фраз
Динамика по дням, регионам, устройствам, площадкам (поиск/РСЯ)
Объявления с текстами и статусами
Группы объявлений
Текущие ставки по ключевым словам

Требования

Python 3.10+
Аккаунт Яндекс с доступом к Метрике и/или Директу
Claude Desktop, Claude Code или Cowork

Установка

1. Клонируйте репозиторий

git clone https://github.com/unklex/yandex-mcp.git
cd yandex-mcp

2. Создайте виртуальное окружение и установите зависимости

# Windows
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

# macOS / Linux
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

3. Получите OAuth-токен

Зайдите на oauth.yandex.com, создайте приложение и в разделе Доступы отметьте нужные права:

metrika:read — для Яндекс.Метрики
direct:api — для Яндекс.Директа

Затем авторизуйтесь под нужным Яндекс-аккаунтом по ссылке:

https://oauth.yandex.com/authorize?response_type=token&client_id=ВАШ_CLIENT_ID

Токен появится в адресной строке браузера после редиректа — скопируйте значение параметра access_token.

4. Узнайте ID счётчика Метрики

Откройте metrika.yandex.ru — ID счётчика отображается под названием сайта в списке счётчиков. Это число вида 12345678.

5. Настройте `.env`

Единственный файл, который нужно заполнить — .env. Скопируйте .env.example в .env и впишите свои данные:

# Обязательно
YANDEX_METRICA_TOKEN=токен_из_шага_3
YANDEX_METRICA_COUNTER_ID=id_из_шага_4

# Если несколько сайтов — через запятую (псевдоним:id)
# YANDEX_METRICA_COUNTERS=site1:12345678,site2:87654321

# Для Яндекс.Директа (если нужен)
# YANDEX_DIRECT_TOKEN=токен_из_шага_3   # можно тот же, если права выданы одному приложению

# Если несколько рекламных аккаунтов
# YANDEX_DIRECT_ACCOUNTS=main:токен1,agency:токен2

# Для агентских аккаунтов
# YANDEX_DIRECT_CLIENT_LOGIN=логин_клиента

Больше никакие файлы редактировать не нужно.

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

6. Claude Desktop

Откройте файл конфигурации:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Добавьте сервер:

{
  "mcpServers": {
    "yandex-metrica": {
      "command": "python",
      "args": ["C:/path/to/yandex-mcp/server.py"],
      "env": {
        "YANDEX_METRICA_TOKEN": "ваш_токен",
        "YANDEX_METRICA_COUNTER_ID": "12345678"
      }
    }
  }
}

Перезапустите Claude Desktop.

6. Claude Code (CLI)

claude mcp add --transport stdio yandex-metrica \
  --env YANDEX_METRICA_TOKEN=ваш_токен \
  --env YANDEX_METRICA_COUNTER_ID=12345678 \
  -- python /path/to/yandex-mcp/server.py

Полный вариант с несколькими счётчиками и Директом:

claude mcp add --transport stdio yandex-metrica \
  --env YANDEX_METRICA_TOKEN=ваш_токен \
  --env YANDEX_METRICA_COUNTER_ID=12345678 \
  --env YANDEX_METRICA_COUNTERS=site1:12345678,site2:87654321 \
  --env YANDEX_DIRECT_ACCOUNTS=main:токен_директа \
  -- python /path/to/yandex-mcp/server.py

6. Cowork

Откройте Settings → Plugins → Add Server вручную, или используйте claude mcp add из Claude Code.

Инструменты

Яндекс.Метрика

Во всех инструментах Метрики параметры date_from / date_to принимают:

YYYY-MM-DD — конкретная дата
today, yesterday
NdaysAgo — например, 30daysAgo

Параметр counter_id — опциональный псевдоним из YANDEX_METRICA_COUNTERS или числовой ID счётчика.

| Инструмент | Что возвращает | |---|---| | get_traffic_summary | Визиты, просмотры, пользователи, отказы, глубина, время на сайте | | get_traffic_sources | Разбивка по источникам: органика, прямые, реклама, соцсети | | get_top_pages | Топ страниц по просмотрам (параметр limit, по умолчанию 20) | | get_goals | Список целей + данные по конверсиям | | get_audience | Устройства, города, регионы, браузеры | | get_realtime | Активность сегодня по часам | | compare_periods | Сравнение метрики между двумя периодами |

Яндекс.Директ

Во всех инструментах Директа:

account — псевдоним аккаунта из YANDEX_DIRECT_ACCOUNTS
client_login — логин клиента (для агентских аккаунтов)
campaign_ids — ID кампаний через запятую, например '123,456'

Допустимые значения date_range:

| Значение | Период | |---|---| | LAST_7_DAYS | Последние 7 дней | | LAST_30_DAYS | Последние 30 дней | | THIS_MONTH | Текущий месяц | | LAST_MONTH | Прошлый месяц | | CUSTOM_DATE | Произвольный период (нужны date_from и date_to) |

Кампании и бюджеты

| Инструмент | Что возвращает | |---|---| | get_direct_campaigns | Список кампаний: ID, название, статус, дневной бюджет (руб.) | | get_direct_top_campaigns | Топ-N кампаний по расходу или кликам (sort_by: Cost/Clicks, top_n) | | get_direct_budget | Суммарный дневной бюджет активных кампаний + остаток Units API |

Статистика

| Инструмент | Что возвращает | |---|---| | get_direct_performance | Клики, показы, расход, CTR, CPC, конверсии, ROI по кампаниям | | get_direct_keywords | Топ ключевых фраз по расходу или кликам (sort_by, top_n) | | get_direct_stats_by_day | Динамика по дням (удобно для анализа трендов) | | get_direct_stats_by_region | Топ регионов/городов по расходу (top_n) | | get_direct_stats_by_device | Компьютер / Смартфон / Планшет | | get_direct_stats_by_placement | Поиск vs РСЯ + стоимость конверсии |

Объявления и ставки

| Инструмент | Что возвращает | |---|---| | get_direct_ads | Тексты, заголовки, ссылки, статусы объявлений. Фильтрация по campaign_ids / adgroup_ids / ad_ids / statuses | | get_direct_adgroups | Группы объявлений: название, тип, статус модерации, статус показов, регионы | | get_direct_bids | Ставки для поиска и РСЯ, приоритет, конкурентная ставка топ-1 |

Примеры запросов

Спросите Claude на русском — он сам выберет нужный инструмент и параметры:

Покажи трафик сайта за последние 7 дней
Какие страницы самые популярные в этом месяце?
Сколько конверсий было вчера?
Сравни визиты этого и прошлого месяца

Покажи все активные кампании Директа
Сколько потратили в Директе за последние 30 дней?
Топ-10 ключевых фраз по расходу за этот месяц
Как распределяется расход между поиском и РСЯ?
Из каких городов приходит больше всего кликов?
Есть ли разница в CTR между мобильными и десктопом?
Покажи тексты объявлений кампании 123456
Какие ставки стоят на ключевых словах в группе 789?

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

Вам нужны только два файла: .env (ваша конфигурация) и server.py (точка запуска). Остальное — внутренняя реализация.

yandex-mcp/
├── .env.example           # ← скопируйте в .env и заполните
├── server.py              # ← путь к этому файлу нужен при регистрации MCP
├── tools/                 # инструменты (не редактировать)
│   ├── traffic.py, sources.py, pages.py, goals.py ...  # Метрика
│   ├── direct_campaigns.py, direct_stats.py ...        # Директ — кампании
│   ├── direct_reports.py                               # Директ — разрезы
│   └── direct_ads.py                                   # Директ — объявления, ставки
└── requirements.txt

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

Ошибка 401 при запросах к Директу Токен не имеет права direct:api. Создайте новый токен через приложение с нужным разрешением.

Ошибка 403 при запросах к Директу Если используется один токен для Метрики и Директа — убедитесь, что приложение имеет доступ к обоим сервисам. Или создайте отдельный токен для Директа.

Нет данных за период Убедитесь, что в кампаниях были показы за указанный период. Кампании без активности не возвращают строк в Reports API.

Предупреждение _units_warning Закончились баллы API Яндекс.Директа (Units). Лимит обновляется каждые 24 часа.

YANDEX_METRICA_TOKEN не задан Убедитесь, что файл .env находится в папке с server.py, или передайте переменные через --env при регистрации MCP.

Технические детали

Яндекс.Метрика:

Авторизация: Authorization: OAuth {token}
Повторные попытки при 429/5xx с экспоненциальным backoff (уважает Retry-After)
Предупреждение _sampling_warning при семплировании данных

Яндекс.Директ:

Авторизация: Authorization: Bearer {token} (отличается от Метрики)
Client-Login как HTTP-заголовок для агентских аккаунтов
Reports API — polling-модель: 201/202 → ждём retryIn сек → 200 → TSV
Ошибки Reports API в XML, не в JSON
Денежные значения в микро-рублях (÷ 1 000 000 = рубли)
Мониторинг Units: предупреждение при остатке < 10% дневного лимита

MCP Servers

Яндекс.Метрика + Директ — MCP Server

Возможности

Требования

Установка

1. Клонируйте репозиторий

2. Создайте виртуальное окружение и установите зависимости

3. Получите OAuth-токен

4. Узнайте ID счётчика Метрики

5. Настройте `.env`

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

6. Claude Desktop

6. Claude Code (CLI)

6. Cowork

Инструменты

Яндекс.Метрика

Яндекс.Директ

Кампании и бюджеты

Статистика

Объявления и ставки

Примеры запросов

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

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

Технические детали

安装包（如果需要）

Cursor 配置 (mcp.json)

Яндекс.Метрика + Директ — MCP Server

Возможности

Требования

Установка

1. Клонируйте репозиторий

2. Создайте виртуальное окружение и установите зависимости

3. Получите OAuth-токен

4. Узнайте ID счётчика Метрики

5. Настройте .env

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

6. Claude Desktop

6. Claude Code (CLI)

6. Cowork

Инструменты

Яндекс.Метрика

Яндекс.Директ

Кампании и бюджеты

Статистика

Объявления и ставки

Примеры запросов

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

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

Технические детали

安装包 （如果需要）

Cursor 配置 (mcp.json)

5. Настройте `.env`

安装包（如果需要）