{
  "markdown": "<!-- mcp-name: io.github.dontsovcmc/yandex-metrika -->\n\n# mcp-server-yandex-metrika\n\n[![Version](https://img.shields.io/badge/version-0.2.4-blue)](https://github.com/dontsovcmc/mcp-server-yandex-metrika)\n\nMCP-сервер, CLI-утилита и библиотека Pydantic-моделей для [API Яндекс Метрики](https://yandex.com/dev/metrika).\n\n- **MCP-сервер** — интеграция с Claude Code, Claude Desktop и другими MCP-клиентами\n- **CLI-утилита** — работа с API из терминала, скрипты и автоматизация\n- **Pydantic-модели** — типизированные модели API для использования в своих Python-программах\n\nВсе данные остаются на вашем компьютере — токен никуда не передаётся.\n\n## Оглавление\n\n- [Возможности](#возможности)\n- [MCP-сервер](#mcp-сервер)\n  - [Установка](#установка)\n  - [Подключение к Claude Code](#подключение-к-claude-code)\n  - [Подключение к Claude Desktop](#подключение-к-claude-desktop)\n  - [Подключение через --mcp-config](#подключение-через---mcp-config)\n  - [Примеры](#примеры-mcp)\n- [CLI-утилита](#cli-утилита)\n  - [Установка](#установка-cli)\n  - [Использование](#использование-cli)\n  - [Примеры команд](#примеры-команд)\n- [Pydantic-модели](#pydantic-модели)\n  - [Установка](#установка-библиотеки)\n  - [Использование в своих программах](#использование-в-своих-программах)\n- [Переменные окружения](#переменные-окружения)\n- [Лимиты API](#лимиты-api)\n- [Разработка](#разработка)\n- [Лицензия](#лицензия)\n\n## Возможности\n\n### Отчёты (Reporting API)\n| Инструмент | CLI | Описание |\n|------------|-----|----------|\n| `ym_stat_data` | `stat-data` | Табличный отчёт по метрикам и измерениям |\n| `ym_stat_data_bytime` | `stat-bytime` | Отчёт по времени (группировка: час/день/неделя/месяц) |\n| `ym_stat_data_drilldown` | `stat-drilldown` | Drill down отчёт с раскрытием уровней |\n| `ym_stat_data_comparison` | `stat-comparison` | Сравнение сегментов/периодов |\n| `ym_stat_data_comparison_drilldown` | — | Сравнение с drill down |\n\n### Счётчики\n| Инструмент | CLI | Описание |\n|------------|-----|----------|\n| `ym_counters` | `counters` | Список счётчиков (поиск, фильтрация) |\n| `ym_counter` | `counter` | Информация о счётчике |\n| `ym_counter_create` | `counter-create` | Создать счётчик |\n| `ym_counter_update` | `counter-update` | Изменить счётчик |\n| `ym_counter_delete` | `counter-delete` | Удалить счётчик |\n| `ym_counter_undelete` | `counter-undelete` | Восстановить удалённый |\n\n### Цели\n| Инструмент | CLI | Описание |\n|------------|-----|----------|\n| `ym_goals` | `goals` | Список целей счётчика |\n| `ym_goal` | `goal` | Информация о цели |\n| `ym_goal_create` | `goal-create` | Создать цель (url/number/step/action/...) |\n| `ym_goal_update` | — | Изменить цель |\n| `ym_goal_delete` | `goal-delete` | Удалить цель |\n\n### Фильтры\n| Инструмент | CLI | Описание |\n|------------|-----|----------|\n| `ym_filters` | `filters` | Список фильтров |\n| `ym_filter` | — | Информация о фильтре |\n| `ym_filter_create` | `filter-create` | Создать фильтр (IP, URL, реферер) |\n| `ym_filter_update` | — | Изменить фильтр |\n| `ym_filter_delete` | `filter-delete` | Удалить фильтр |\n\n### Доступ (Grants)\n| Инструмент | CLI | Описание |\n|------------|-----|----------|\n| `ym_grants` | `grants` | Список разрешений |\n| `ym_grant_create` | `grant-create` | Выдать разрешение |\n| `ym_grant_update` | — | Изменить разрешение |\n| `ym_grant_delete` | `grant-delete` | Удалить разрешение |\n\n### Операции\n| Инструмент | CLI | Описание |\n|------------|-----|----------|\n| `ym_operations` | `operations` | Список операций |\n| `ym_operation` | — | Информация об операции |\n| `ym_operation_create` | `operation-create` | Создать операцию (cut_parameter, to_lower, ...) |\n| `ym_operation_update` | — | Изменить операцию |\n| `ym_operation_delete` | `operation-delete` | Удалить операцию |\n\n### Сегменты\n| Инструмент | CLI | Описание |\n|------------|-----|----------|\n| `ym_segments` | `segments` | Список сегментов |\n| `ym_segment` | — | Информация о сегменте |\n| `ym_segment_create` | `segment-create` | Создать сегмент |\n| `ym_segment_update` | — | Изменить сегмент |\n| `ym_segment_delete` | `segment-delete` | Удалить сегмент |\n\n### Метки\n| Инструмент | CLI | Описание |\n|------------|-----|----------|\n| `ym_labels` | `labels` | Список меток |\n| `ym_label_create` | `label-create` | Создать метку |\n| `ym_label_update` | — | Изменить метку |\n| `ym_label_delete` | `label-delete` | Удалить метку |\n| `ym_counter_label_set` | — | Привязать метку к счётчику |\n| `ym_counter_label_unset` | — | Отвязать метку |\n\n### Аккаунты и представители\n| Инструмент | CLI | Описание |\n|------------|-----|----------|\n| `ym_accounts` | `accounts` | Список аккаунтов |\n| `ym_account_delete` | — | Удалить аккаунт |\n| `ym_delegates` | `delegates` | Список представителей |\n| `ym_delegate_add` | `delegate-add` | Добавить представителя |\n| `ym_delegate_delete` | `delegate-delete` | Удалить представителя |\n\n### Примечания на графике\n| Инструмент | CLI | Описание |\n|------------|-----|----------|\n| `ym_chart_annotations` | `chart-annotations` | Список примечаний |\n| `ym_chart_annotation_create` | `chart-annotation-create` | Создать примечание |\n| `ym_chart_annotation_update` | — | Изменить примечание |\n| `ym_chart_annotation_delete` | — | Удалить примечание |\n\n### Фильтры доступа\n| Инструмент | CLI | Описание |\n|------------|-----|----------|\n| `ym_access_filters` | — | Список фильтров доступа |\n| `ym_access_filter_create` | — | Создать фильтр доступа |\n| `ym_access_filter_update` | — | Изменить фильтр доступа |\n| `ym_access_filter_delete` | — | Удалить фильтр доступа |\n\n### Logs API\n| Инструмент | CLI | Описание |\n|------------|-----|----------|\n| `ym_log_requests` | `log-requests` | Список запросов логов |\n| `ym_log_request` | — | Информация о запросе |\n| `ym_log_request_create` | `log-request-create` | Создать запрос (hits/visits) |\n| `ym_log_request_evaluate` | `log-request-evaluate` | Оценить возможность запроса |\n| `ym_log_request_clean` | — | Очистить обработанные логи |\n| `ym_log_request_cancel` | — | Отменить запрос |\n| `ym_log_request_download` | `log-download` | Скачать часть лога (TSV) |\n\n### Импорт данных\n| Инструмент | CLI | Описание |\n|------------|-----|----------|\n| `ym_offline_conversions_upload` | `upload-conversions` | Загрузить оффлайн-конверсии |\n| `ym_offline_conversions_uploads` | — | Список загрузок конверсий |\n| `ym_offline_conversion_upload_info` | — | Инфо о загрузке |\n| `ym_calls_upload` | `upload-calls` | Загрузить звонки |\n| `ym_calls_uploads` | — | Список загрузок звонков |\n| `ym_calls_upload_info` | — | Инфо о загрузке звонков |\n| `ym_expenses_upload` | `upload-expenses` | Загрузить расходы |\n| `ym_user_params_upload` | — | Загрузить параметры пользователей |\n\n---\n\n## MCP-сервер\n\n### Установка\n\n#### Шаг 1. Получить OAuth-токен Яндекс Метрики\n\n1. Зарегистрируйте приложение на [oauth.yandex.com](https://oauth.yandex.com/client/new)\n2. Укажите права: `metrika:read`, `metrika:write`\n3. Получите токен: `https://oauth.yandex.com/authorize?response_type=token&client_id=<ваш_client_id>`\n\n#### Шаг 2. Подключить MCP-сервер\n\n### Подключение к Claude Code\n\n**Способ 1: через uvx** (не требует установки пакета)\n\n> Требуется [uv](https://docs.astral.sh/uv/) — если не установлен:\n> ```bash\n> curl -LsSf https://astral.sh/uv/install.sh | sh\n> ```\n\n```bash\nclaude mcp add yandex-metrika \\\n  -e YANDEX_METRIKA_TOKEN=ваш_токен \\\n  -- uvx mcp-server-yandex-metrika\n```\n\n**Способ 2: через pip**\n\n```bash\npip install mcp-server-yandex-metrika\n\nclaude mcp add yandex-metrika \\\n  -e YANDEX_METRIKA_TOKEN=ваш_токен \\\n  -- mcp-server-yandex-metrika\n```\n\nДля удаления:\n```bash\nclaude mcp remove yandex-metrika\n```\n\n### Подключение к Claude Desktop\n\nДобавьте в конфигурационный файл:\n\n| Клиент | ОС | Путь к файлу |\n|--------|----|-------------|\n| Claude Code | все | `~/.claude/settings.json` (секция `mcpServers`) |\n| Claude Desktop | macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |\n| Claude Desktop | Windows | `%APPDATA%\\Claude\\claude_desktop_config.json` |\n| Claude Desktop | Linux | `~/.config/Claude/claude_desktop_config.json` |\n\n**Через uvx:**\n```json\n{\n  \"mcpServers\": {\n    \"yandex-metrika\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-server-yandex-metrika\"],\n      \"env\": {\n        \"YANDEX_METRIKA_TOKEN\": \"ваш_токен\"\n      }\n    }\n  }\n}\n```\n\n**Через pip** (после `pip install mcp-server-yandex-metrika`):\n```json\n{\n  \"mcpServers\": {\n    \"yandex-metrika\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"mcp_server_yandex_metrika\"],\n      \"env\": {\n        \"YANDEX_METRIKA_TOKEN\": \"ваш_токен\"\n      }\n    }\n  }\n}\n```\n\n### Подключение через --mcp-config\n\nПодключает сервер только на время одной сессии Claude, не сохраняя в настройки. Токен хранится в отдельном `.env.mcp` файле, а не в конфиге Claude.\n\nИз JSON-строки:\n```bash\nclaude --mcp-config '{\"yandex-metrika\":{\"command\":\"bash\",\"args\":[\"-c\",\"source ~/.env.mcp && exec uvx mcp-server-yandex-metrika\"]}}'\n```\n\nИз файла:\n```bash\nclaude --mcp-config ~/mcp-servers.json\n```\n\nПример `~/mcp-servers.json`:\n```json\n{\n  \"yandex-metrika\": {\n    \"command\": \"bash\",\n    \"args\": [\"-c\", \"source ~/.env.mcp && exec uvx mcp-server-yandex-metrika\"]\n  }\n}\n```\n\nПример `~/.env.mcp`:\n```\nYANDEX_METRIKA_TOKEN=ваш_токен\n```\n\n#### Шаг 3. Проверить\n\nПопросите Claude: *«Покажи список моих счётчиков Яндекс Метрики»* — он вызовет `ym_counters`.\n\n### Примеры (MCP)\n\n- «Покажи статистику по визитам за последнюю неделю для счётчика 12345678» → `ym_stat_data`\n- «Создай цель \"Покупка\" типа url с условием contain \"/thank-you\"» → `ym_goal_create`\n- «Выгрузи логи визитов за январь 2024» → `ym_log_request_create`\n\n---\n\n## CLI-утилита\n\n### Установка (CLI)\n\n```bash\npip install mcp-server-yandex-metrika\n```\n\nПеременная окружения `YANDEX_METRIKA_TOKEN` должна быть установлена:\n\n```bash\nexport YANDEX_METRIKA_TOKEN=ваш_токен\n```\n\nИли через файл:\n\n```bash\nmcp-server-yandex-metrika --env /path/to/.env counters\n```\n\nФормат файла — `KEY=VALUE`, по одной переменной на строку, `#`-комментарии.\n\n### Использование (CLI)\n\nБез аргументов запускается MCP-сервер, с командой — CLI. Все команды выводят JSON.\n\n```bash\n# Версия\nmcp-server-yandex-metrika --version\n\n# Справка\nmcp-server-yandex-metrika --help\nmcp-server-yandex-metrika <command> --help\n```\n\n### Примеры команд\n\n```bash\n# Статистика визитов\nmcp-server-yandex-metrika stat-data --ids 12345678 --metrics ym:s:visits,ym:s:users\n\n# Список счётчиков\nmcp-server-yandex-metrika counters --search \"мой сайт\"\n\n# Цели счётчика\nmcp-server-yandex-metrika goals 12345678\n\n# Создать запрос логов\nmcp-server-yandex-metrika log-request-create 12345678 \\\n  --date1 2024-01-01 --date2 2024-01-31 \\\n  --fields \"ym:s:date,ym:s:visitID\" --source visits\n```\n\n---\n\n## Pydantic-модели\n\nПакет содержит типизированные Pydantic-модели всех объектов API. Модели можно использовать в своих Python-программах для валидации данных и автодополнения в IDE.\n\n### Установка (библиотеки)\n\n```bash\npip install mcp-server-yandex-metrika\n```\n\n### Использование в своих программах\n\n```python\nfrom mcp_server_yandex_metrika.models import CounterBrief, Goal\n\n# Валидация данных из API\ndata = {\"id\": 12345678, \"name\": \"Мой сайт\", \"status\": \"Active\"}\ncounter = CounterBrief.model_validate(data)\nprint(counter.name)  # type-safe доступ к полям\n\n# Создание объекта\ngoal = Goal(name=\"Покупка\", type=\"url\")\nprint(goal.model_dump_json())\n```\n\nВсе модели используют `extra=\"allow\"` для forward compatibility — неизвестные поля API не вызывают ошибок.\n\nПолный список моделей: [`models.py`](src/mcp_server_yandex_metrika/models.py)\n\n---\n\n## Переменные окружения\n\n| Переменная | Обязательная | По умолчанию | Описание |\n|------------|:------------:|:------------:|----------|\n| `YANDEX_METRIKA_TOKEN` | да | — | OAuth-токен Яндекс Метрики |\n| `METRIKA_TIMEOUT` | нет | `30` | Таймаут HTTP-запросов к API (секунды) |\n| `METRIKA_FILE_TIMEOUT` | нет | `60` | Таймаут скачивания файлов (секунды) |\n\n### Загрузка из файла\n\nВместо передачи переменных через `-e` можно указать файл:\n\n```bash\nmcp-server-yandex-metrika --env /path/to/.env\n```\n\nФормат файла — `KEY=VALUE`, по одной переменной на строку, `#`-комментарии.\n\nРаботает в обоих режимах: MCP-сервер и CLI:\n\n```bash\n# MCP-сервер\nclaude mcp add yandex-metrika -- mcp-server-yandex-metrika --env ~/.config/metrika.env\n\n# CLI\nmcp-server-yandex-metrika --env ~/.config/metrika.env counters\n```\n\n## Лимиты API\n\n- 30 запросов/секунду на IP\n- 5000 запросов/день на пользователя\n- 3 параллельных запроса на пользователя\n- 200 запросов/5 минут для `/stat/v1/data/`\n- HTTP 420 при превышении лимитов\n\n## Разработка\n\n```bash\npip install -e \".[test]\"\nruff check src/ tests/\npytest tests/ -v\n```\n\n## Лицензия\n\nMIT\n",
  "bytes": 12605,
  "sha": "4d6c6359507fe83e62e0c193b67a227a7b82884acc864c41de4594dd9d8e9cce",
  "repo_slug": "dontsovcmc/mcp-server-yandex-metrika",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_dontsovcmc_yandex_metrika_2e766086/readme"
}