# yandex-metrika-mcp

Hardened форк [atomkraft/yandex-metrika-mcp](https://github.com/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](docs/SECURITY.md), запиненное дерево зависимостей, метаданные репо.

---

## Токен

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

1. [Создай приложение](https://oauth.yandex.ru/client/new): платформа — **веб-сервисы**; 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)

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

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

```sh
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

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

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

```sh
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](README_en.md).

---

## Разработка

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

## Лицензия

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