Yandex Metrica MCP

MCP-сервер для Yandex Metrica (Яндекс Метрика): спрашивайте веб-аналитику — посещаемость, источники, поведение и конверсии по целям — из Claude, Cursor, Codex и других AI-клиентов на естественном языке.

Ассистент сам находит счётчики, тянет статистику из Reporting API и сопоставляет цели с конверсиями — то, что в интерфейсе Метрики приходится собирать вручную по отчётам.

_{Настоящая MCP-сессия: реальный сервер, хендшейк и tools/call по stdio через официальный SDK; ответы Яндекс Метрики — записанные фикстуры (<a href="docs/demo">docs/demo</a>), поэтому демо воспроизводится без токена и сети — <a href="docs/demo.tape">vhs docs/demo.tape</a>.}

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

1. Получите токен — своё OAuth-приложение Яндекса, ~5 минут, без кода.

2. Добавьте сервер — например, в Claude Code (другие клиенты):

   Copy & paste — that's itCopy

   claude mcp add yandex-metrica -e YANDEX_METRIKA_TOKEN=ваш_токен -- npx -y mcp-yandex-metrica

3. Спросите ассистента: «Какая конверсия по цели "Оформление заказа" за 30 дней?»

Без установки: Метрика входит в удалённый сервер Яндекс Директа — добавьте https://mcp.askads.ru/mcp по URL (инструкция), инструменты Метрики видны с префиксом metrika_.

Что умеет

• Счётчики и цели — list_counters (счётчики, к которым есть доступ) и list_goals (цели/конверсии счётчика) через Management API.
• Статистика — get_statistics по Reporting API (stat/v1/data): метрики и измерения, период (в т.ч. относительный — 7daysAgo), фильтры, сортировка, авто-пагинация.
• Конверсии — метрики целей ym:s:goal<id>reaches / ym:s:goal<id>conversionRate.
• Честная выборка — ответ несёт totals (итог по всем строкам) и sampled/sample_share, чтобы было видно, когда данные семплированы.
• Универсальный raw_request — прямой вызов любого пути API; GET свободно, запись (POST/DELETE) только по confirmWrite=true.
• Устойчивость — ретраи на 429/5xx с бэкоффом и таймаут запроса.

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

Попросите ассистента на русском — например:

• «Сколько визитов и какой процент отказов за последнюю неделю?»
• «Покажи трафик по источникам за июнь — сгруппируй по ym:s:lastTrafficSource»
• «Какая конверсия по цели "Оформление заказа" за 30 дней?»
• «Найди счётчик по домену shop.example и покажи его цели»

Установка

claude mcp add yandex-metrica -e YANDEX_METRIKA_TOKEN=ваш_токен -- npx -y mcp-yandex-metrica

Либо через маркетплейс плагинов — токен спросится диалогом при включении и сохранится в системном keychain (не в конфиге открытым текстом):

/plugin marketplace add askads/claude-plugins
/plugin install yandex-metrica@askads

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

{
  "mcpServers": {
    "yandex-metrica": {
      "command": "npx",
      "args": ["-y", "mcp-yandex-metrica"],
      "env": { "YANDEX_METRIKA_TOKEN": "ваш_токен" }
    }
  }
}

~/.cursor/mcp.json (или .cursor/mcp.json в проекте)

{
  "mcpServers": {
    "yandex-metrica": {
      "command": "npx",
      "args": ["-y", "mcp-yandex-metrica"],
      "env": { "YANDEX_METRIKA_TOKEN": "ваш_токен" }
    }
  }
}

[mcp_servers.yandex-metrica]
command = "npx"
args = ["-y", "mcp-yandex-metrica"]

[mcp_servers.yandex-metrica.env]
YANDEX_METRIKA_TOKEN = "ваш_токен"

.vscode/mcp.json — ключ servers (не mcpServers)

{
  "servers": {
    "yandex-metrica": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-yandex-metrica"],
      "env": { "YANDEX_METRIKA_TOKEN": "ваш_токен" }
    }
  }
}

Получение токена

Нужен OAuth-токен с правом «Получение статистики, чтение параметров своих и доверенных счётчиков» (scope metrika:read). Два способа.

Быстрый — ссылка Ask Ads. Откройте ссылку под аккаунтом с доступом к нужным счётчикам и подтвердите доступ:

→ Получить токен

Браузер вернёт вас на сайт Ask Ads — токен покажется во всплывающем окне, скопируйте его в YANDEX_METRIKA_TOKEN. ⚠️ Приложение общее с mcp-yandex-direct, поэтому токен даёт не только чтение Метрики, но и полный доступ к Яндекс Директу — если это лишнее, используйте второй способ.

Минимальный — своё приложение (только metrika:read).

1. Откройте oauth.yandex.ru → Создать приложение. Платформа — «Веб-сервисы», Redirect URI — https://oauth.yandex.ru/verification_code.
2. В правах доступа отметьте Яндекс.Метрика → «Получение статистики, чтение параметров своих и доверенных счётчиков» и сохраните. Скопируйте ClientID приложения.
3. Откройте в браузере — под аккаунтом с доступом к нужным счётчикам: https://oauth.yandex.ru/authorize?response_type=token&client_id=<ваш ClientID> — подтвердите доступ, и токен покажется прямо на странице.
4. Скопируйте токен в переменную YANDEX_METRIKA_TOKEN.

⚠️ Токен даёт доступ к данным аналитики и хранится открытым текстом в конфиге — относитесь к нему как к паролю.

Настройка

Полный список инструментов — в docs/TOOLS.md.

Требования

• Node.js 20+ (запускается через npx, отдельная установка не нужна).
• OAuth-токен Метрики — см. Получение токена.

Ограничения

• Read-only MVP — изменяющих операций нет; запись доступна только через raw_request с явным confirmWrite=true.
• Reporting API может семплировать данные на больших периодах — смотрите sampled/sample_share в ответе и при необходимости передавайте accuracy: "full".
• У Метрики нет песочницы — все вызовы идут к боевому API (но MVP только читает).

Документация

• Все инструменты
• Разработка

Смотрите также

• Ask Ads — чат-аналитик и «Сторож» рекламных кабинетов от авторов этого сервера: алерты о сливах бюджета и поломках трекинга — в Telegram.
• askads/claude-plugins — маркетплейс плагинов Claude: серверы Ask Ads ставятся одной командой, токены спрашиваются при включении.

Поддержка

Вопросы, идеи и доработки — пишите в Telegram: @gistrec.

Лицензия

MIT — см. LICENSE.