yandex-metrika-mcp

Hardened форк atomkraft/yandex-metrika-mcp. Доступ к аналитике Яндекс.Метрики из MCP-клиента (Claude Code, Cursor и другие). Только чтение — сервер отдаёт исключительно отчёты Stat API, ничего в аккаунте Метрики не меняет. Ставится через npx прямо из git.

---

Почему read-only и зачем форк

У Метрики есть write-операции (создание счётчиков, загрузка данных), но в этом MCP они не реализованы — только отчётные инструменты. Поэтому, в отличие от yandex-direct-mcp, здесь нет флагов «включить запись»: гейтить нечего, безопасный режим — единственный.

Что добавил форк поверх upstream:

• npx-установка (bin + shebang) — не нужно вручную собирать и звать node build/index.js.
• Фикс бага: get_visits теперь учитывает date_from/date_to (в upstream даты игнорировались); даты прокинуты во все пресетные отчёты.
• Error handling: сбои возвращаются как MCP-результат с isError: true, а не заворачиваются в обычный текст.
• Провенанс (NOTICE), docs/SECURITY.md, запиненное дерево зависимостей, метаданные репо.

---

Токен

Сервер авторизуется статичным OAuth-токеном в переменной YANDEX_API_KEY. Запрашивай только scope metrika:read (см. docs/SECURITY.md).

1. Создай приложение: платформа — веб-сервисы; redirect URI — https://oauth.yandex.ru/verification_code; доступ — только metrika:read.
2. Скопируй ClientID приложения.
3. Открой ссылку https://oauth.yandex.ru/authorize?response_type=token&client_id=<ClientID>.
4. Скопируй токен со страницы — это значение YANDEX_API_KEY.

---

Установка

Claude Code (рекомендуемо — npx из git)

claude mcp add yandex-metrika \
  --env YANDEX_API_KEY=ВАШ_ТОКЕН \
  -- npx -y github:nikolaymokh-dev/yandex-metrika-mcp

Пин на тег (после релиза):

claude mcp add yandex-metrika \
  --env YANDEX_API_KEY=ВАШ_ТОКЕН \
  -- npx -y github:nikolaymokh-dev/yandex-metrika-mcp#v0.1.0

.mcp.json / .claude.json / Cursor

{
  "mcpServers": {
    "yandex-metrika": {
      "command": "npx",
      "args": ["-y", "github:nikolaymokh-dev/yandex-metrika-mcp"],
      "env": { "YANDEX_API_KEY": "ВАШ_ТОКЕН" }
    }
  }
}

Из локальной сборки

git clone https://github.com/nikolaymokh-dev/yandex-metrika-mcp
cd yandex-metrika-mcp && npm ci && npm run build
YANDEX_API_KEY=ВАШ_ТОКЕН node build/index.js

---

Инструменты (26, все read-only)

Каждый принимает counter_id; большинство — опциональные date_from/date_to (YYYY-MM-DD).

Группа	Инструменты
Аккаунт / визиты	get_account_info, get_visits, get_data_by_time
Источники трафика	sources_summary, sources_search_phrases, get_traffic_sources_types, get_search_engines_data, get_new_users_by_source
Контент-аналитика	get_content_analytics_sources, ..._categories, ..._authors, ..._topics, ..._articles
Аудитория / устройства	get_user_demographics, get_device_analysis, get_browsers_report, get_mobile_vs_desktop
Гео	get_regional_data, get_geographical_organic_traffic
Поведение / конверсии	get_page_depth_analysis, get_page_performance, get_goals_conversion, get_conversion_rate_by_source_and_landing
Поиск / эксперименты	get_organic_search_performance, get_yandex_direct_experiment
E-commerce	get_ecommerce_performance

Полное описание каждого инструмента (на английском) — в README_en.md.

---

Разработка

npm ci
npm run build        # tsc → build/
npm run inspector    # MCP Inspector

Лицензия

MIT. Форк atomkraft/yandex-metrika-mcp (© Vadim Bezymiannyi). Изменения © 2026 nikolaymokh-dev. См. NOTICE и LICENSE.