{"type": "text"}

@rezlazy/yandex-metrika-mcp

MCP-сервер для Yandex Metrika Reports API (/stat/v1/*) и Management API (/management/v1/*).

Предоставляет 68 инструментов: 6 инструментов для отчетов и 62 инструмента управления (счетчики, цели, фильтры, доступы, сегменты, метки и другое).

Требования

• Node.js 20+

• OAuth-токен с правами metrika:read (отчеты) и/или metrika:write (создание/изменение/удаление)

Related MCP server: Google Analytics MCP Server

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

1. Создайте приложение Yandex OAuth — выберите Для доступа к API или отладки.

2. Добавьте права metrika:read (отчеты) и metrika:write (изменения в управлении).

3. Скопируйте Client ID приложения.

4. Откройте в браузере:

   https://oauth.yandex.ru/authorize?response_type=token&client_id=<CLIENT_ID>

5. Скопируйте токен из URL перенаправления (access_token=...).

См. документацию по авторизации Yandex Metrika.

Настройка Cursor

Добавьте в .cursor/mcp.json или в настройки MCP в Cursor:

{
  "mcpServers": {
    "yandex-metrika": {
      "command": "npx",
      "args": ["-y", "@rezlazy/yandex-metrika-mcp"],
      "env": {
        "METRIKA_TOKEN": "<your-oauth-token>"
      }
    }
  }
}

Для локальной разработки (.cursor/mcp.json в этом репозитории):

{
  "mcpServers": {
    "yandex-metrika": {
      "type": "stdio",
      "command": "node",
      "args": ["${workspaceFolder}/dist/index.js"],
      "envFile": "${workspaceFolder}/.env"
    }
  }
}

Создайте .env в корне проекта:

METRIKA_TOKEN=your_oauth_token

Запуск MCP-сервера

Сервер использует stdio (stdin/stdout), а не HTTP. Вы не запускаете его как веб-сервер — ваш MCP-клиент (например, Cursor) запускает его как дочерний процесс.

Требования: Node.js 20+, METRIKA_TOKEN и собранный dist/index.js (для локальной разработки).

В Cursor (рекомендуется)

1. Настройте MCP в .cursor/mcp.json или в настройках MCP в Cursor (см. примеры выше).

2. Настройки → MCP → Refresh или перезапустите Cursor.

Cursor автоматически запускает node dist/index.js (локально) или npx @rezlazy/yandex-metrika-mcp (npm) при использовании инструментов. Если что-то не работает, проверьте Вывод → MCP Logs.

Из GitHub (без публикации в npm)

{
  "mcpServers": {
    "yandex-metrika": {
      "command": "npx",
      "args": ["-y", "github:Rezlazy/yandex-metrika-mcp"],
      "env": {
        "METRIKA_TOKEN": "<your-oauth-token>"
      }
    }
  }
}

Для установки из git в репозитории должен существовать dist/ или сборка при установке (например, через скрипт prepare).

Ручной запуск (только для отладки)

npm run build
export METRIKA_TOKEN=your_oauth_token
node dist/index.js

Процесс молча ожидает JSON-RPC на stdin — это нормально. Без METRIKA_TOKEN он завершается с ошибкой.

Мультикорневое рабочее пространство (*.code-workspace)

Если вы открываете mcp.code-workspace (несколько папок в одном окне), Cursor может не показывать проектные MCP-серверы из .cursor/mcp.json в Настройках → MCP. Это известное ограничение Cursor.

Обходные пути:

1. Откройте этот репозиторий напрямую: Файл → Открыть папку → yandex-metrika-mcp (не файл .code-workspace).

2. Или добавьте в глобальный конфиг ~/.cursor/mcp.json (работает в мультикорневом режиме):

"yandex-metrika": {
  "type": "stdio",
  "command": "node",
  "args": ["/absolute/path/to/yandex-metrika-mcp/dist/index.js"],
  "envFile": "/absolute/path/to/yandex-metrika-mcp/.env"
}

После изменения конфигурации: обновите MCP в настройках или перезапустите Cursor. Проверьте логи: панель вывода → MCP Logs.

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

Инструменты

Отчеты (stat_*) — 6 инструментов

Управление (mgmt_*) — 62 инструмента

Охватывает Management API: счетчики, цели, фильтры, операции, доступы, фильтры доступа, сегменты, аннотации на графиках, метки, аккаунты, делегаты, клиенты, облачные выгрузки.

Общие инструменты управления:

Для методов POST/PUT передавайте JSON в параметре body (см. форматы API). Пример создания счетчика:

{
  "body": {
    "counter": {
      "name": "My site",
      "site": "example.com"
    }
  }
}

Параметры отчетов

• ids — идентификатор(ы) счетчика, через запятую

• metrics — например, ym:s:visits, ym:s:users, ym:s:pageviews

• dimensions — например, ym:s:trafficSource, ym:s:operatingSystem

• date1 / date2 — период (7daysAgo, today или YYYY-MM-DD)

• filters — выражение сегментации

• preset — пресет отчета

• format — json (по умолчанию) или csv

Полный список метрик и измерений: attrandmetr.

Пример: визиты по источникам трафика

Инструмент: stat_data

{
  "ids": "44147844",
  "metrics": "ym:s:visits,ym:s:users",
  "dimensions": "ym:s:trafficSource",
  "date1": "30daysAgo",
  "date2": "today",
  "sort": "-ym:s:visits",
  "limit": "10"
}

Пример: тренд ежедневных визитов

Инструмент: stat_bytime

{
  "ids": "44147844",
  "metrics": "ym:s:visits",
  "date1": "30daysAgo",
  "date2": "today",
  "group": "day"
}

Разработка

npm install
npm run typecheck
npm test
npm run build

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

Публикация автоматизирована через GitHub Actions при публикации релиза GitHub.

Одноразовая настройка:

1. Создайте организацию/скоуп npm @rezlazy на npmjs.com.

2. Сгенерируйте Automation-токен npm.

3. Добавьте секрет NPM_TOKEN в репозиторий GitHub.

4. Создайте релиз с тегом v0.1.0 — workflow опубликует @rezlazy/yandex-metrika-mcp.

Лицензия

MIT