io.github.dontsovcmc/yandex-metrika
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@io.github.dontsovcmc/yandex-metrika get visitors for last 7 days"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-server-yandex-metrika
MCP-сервер, CLI-утилита и библиотека Pydantic-моделей для API Яндекс Метрики.
MCP-сервер — интеграция с Claude Code, Claude Desktop и другими MCP-клиентами
CLI-утилита — работа с API из терминала, скрипты и автоматизация
Pydantic-модели — типизированные модели API для использования в своих Python-программах
Все данные остаются на вашем компьютере — токен никуда не передаётся.
Оглавление
Related MCP server: ya-metrics-mcp
Возможности
Отчёты (Reporting API)
Инструмент | CLI | Описание |
|
| Табличный отчёт по метрикам и измерениям |
|
| Отчёт по времени (группировка: час/день/неделя/месяц) |
|
| Drill down отчёт с раскрытием уровней |
|
| Сравнение сегментов/периодов |
| — | Сравнение с drill down |
Счётчики
Инструмент | CLI | Описание |
|
| Список счётчиков (поиск, фильтрация) |
|
| Информация о счётчике |
|
| Создать счётчик |
|
| Изменить счётчик |
|
| Удалить счётчик |
|
| Восстановить удалённый |
Цели
Инструмент | CLI | Описание |
|
| Список целей счётчика |
|
| Информация о цели |
|
| Создать цель (url/number/step/action/...) |
| — | Изменить цель |
|
| Удалить цель |
Фильтры
Инструмент | CLI | Описание |
|
| Список фильтров |
| — | Информация о фильтре |
|
| Создать фильтр (IP, URL, реферер) |
| — | Изменить фильтр |
|
| Удалить фильтр |
Доступ (Grants)
Инструмент | CLI | Описание |
|
| Список разрешений |
|
| Выдать разрешение |
| — | Изменить разрешение |
|
| Удалить разрешение |
Операции
Инструмент | CLI | Описание |
|
| Список операций |
| — | Информация об операции |
|
| Создать операцию (cut_parameter, to_lower, ...) |
| — | Изменить операцию |
|
| Удалить операцию |
Сегменты
Инструмент | CLI | Описание |
|
| Список сегментов |
| — | Информация о сегменте |
|
| Создать сегмент |
| — | Изменить сегмент |
|
| Удалить сегмент |
Метки
Инструмент | CLI | Описание |
|
| Список меток |
|
| Создать метку |
| — | Изменить метку |
|
| Удалить метку |
| — | Привязать метку к счётчику |
| — | Отвязать метку |
Аккаунты и представители
Инструмент | CLI | Описание |
|
| Список аккаунтов |
| — | Удалить аккаунт |
|
| Список представителей |
|
| Добавить представителя |
|
| Удалить представителя |
Примечания на графике
Инструмент | CLI | Описание |
|
| Список примечаний |
|
| Создать примечание |
| — | Изменить примечание |
| — | Удалить примечание |
Фильтры доступа
Инструмент | CLI | Описание |
| — | Список фильтров доступа |
| — | Создать фильтр доступа |
| — | Изменить фильтр доступа |
| — | Удалить фильтр доступа |
Logs API
Инструмент | CLI | Описание |
|
| Список запросов логов |
| — | Информация о запросе |
|
| Создать запрос (hits/visits) |
|
| Оценить возможность запроса |
| — | Очистить обработанные логи |
| — | Отменить запрос |
|
| Скачать часть лога (TSV) |
Импорт данных
Инструмент | CLI | Описание |
|
| Загрузить оффлайн-конверсии |
| — | Список загрузок конверсий |
| — | Инфо о загрузке |
|
| Загрузить звонки |
| — | Список загрузок звонков |
| — | Инфо о загрузке звонков |
|
| Загрузить расходы |
| — | Загрузить параметры пользователей |
MCP-сервер
Установка
Шаг 1. Получить OAuth-токен Яндекс Метрики
Зарегистрируйте приложение на oauth.yandex.com
Укажите права:
metrika:read,metrika:writeПолучите токен:
https://oauth.yandex.com/authorize?response_type=token&client_id=<ваш_client_id>
Шаг 2. Подключить MCP-сервер
Подключение к Claude Code
Способ 1: через uvx (не требует установки пакета)
Требуется uv — если не установлен:
curl -LsSf https://astral.sh/uv/install.sh | sh
claude mcp add yandex-metrika \
-e YANDEX_METRIKA_TOKEN=ваш_токен \
-- uvx mcp-server-yandex-metrikaСпособ 2: через pip
pip install mcp-server-yandex-metrika
claude mcp add yandex-metrika \
-e YANDEX_METRIKA_TOKEN=ваш_токен \
-- mcp-server-yandex-metrikaДля удаления:
claude mcp remove yandex-metrikaПодключение к Claude Desktop
Добавьте в конфигурационный файл:
Клиент | ОС | Путь к файлу |
Claude Code | все |
|
Claude Desktop | macOS |
|
Claude Desktop | Windows |
|
Claude Desktop | Linux |
|
Через uvx:
{
"mcpServers": {
"yandex-metrika": {
"command": "uvx",
"args": ["mcp-server-yandex-metrika"],
"env": {
"YANDEX_METRIKA_TOKEN": "ваш_токен"
}
}
}
}Через pip (после pip install mcp-server-yandex-metrika):
{
"mcpServers": {
"yandex-metrika": {
"command": "python",
"args": ["-m", "mcp_server_yandex_metrika"],
"env": {
"YANDEX_METRIKA_TOKEN": "ваш_токен"
}
}
}
}Подключение через --mcp-config
Подключает сервер только на время одной сессии Claude, не сохраняя в настройки. Токен хранится в отдельном .env.mcp файле, а не в конфиге Claude.
Из JSON-строки:
claude --mcp-config '{"yandex-metrika":{"command":"bash","args":["-c","source ~/.env.mcp && exec uvx mcp-server-yandex-metrika"]}}'Из файла:
claude --mcp-config ~/mcp-servers.jsonПример ~/mcp-servers.json:
{
"yandex-metrika": {
"command": "bash",
"args": ["-c", "source ~/.env.mcp && exec uvx mcp-server-yandex-metrika"]
}
}Пример ~/.env.mcp:
YANDEX_METRIKA_TOKEN=ваш_токенШаг 3. Проверить
Попросите Claude: «Покажи список моих счётчиков Яндекс Метрики» — он вызовет ym_counters.
Примеры (MCP)
«Покажи статистику по визитам за последнюю неделю для счётчика 12345678» →
ym_stat_data«Создай цель "Покупка" типа url с условием contain "/thank-you"» →
ym_goal_create«Выгрузи логи визитов за январь 2024» →
ym_log_request_create
CLI-утилита
Установка (CLI)
pip install mcp-server-yandex-metrikaПеременная окружения YANDEX_METRIKA_TOKEN должна быть установлена:
export YANDEX_METRIKA_TOKEN=ваш_токенИли через файл:
mcp-server-yandex-metrika --env /path/to/.env countersФормат файла — KEY=VALUE, по одной переменной на строку, #-комментарии.
Использование (CLI)
Без аргументов запускается MCP-сервер, с командой — CLI. Все команды выводят JSON.
# Версия
mcp-server-yandex-metrika --version
# Справка
mcp-server-yandex-metrika --help
mcp-server-yandex-metrika <command> --helpПримеры команд
# Статистика визитов
mcp-server-yandex-metrika stat-data --ids 12345678 --metrics ym:s:visits,ym:s:users
# Список счётчиков
mcp-server-yandex-metrika counters --search "мой сайт"
# Цели счётчика
mcp-server-yandex-metrika goals 12345678
# Создать запрос логов
mcp-server-yandex-metrika log-request-create 12345678 \
--date1 2024-01-01 --date2 2024-01-31 \
--fields "ym:s:date,ym:s:visitID" --source visitsPydantic-модели
Пакет содержит типизированные Pydantic-модели всех объектов API. Модели можно использовать в своих Python-программах для валидации данных и автодополнения в IDE.
Установка (библиотеки)
pip install mcp-server-yandex-metrikaИспользование в своих программах
from mcp_server_yandex_metrika.models import CounterBrief, Goal
# Валидация данных из API
data = {"id": 12345678, "name": "Мой сайт", "status": "Active"}
counter = CounterBrief.model_validate(data)
print(counter.name) # type-safe доступ к полям
# Создание объекта
goal = Goal(name="Покупка", type="url")
print(goal.model_dump_json())Все модели используют extra="allow" для forward compatibility — неизвестные поля API не вызывают ошибок.
Полный список моделей: models.py
Переменные окружения
Переменная | Обязательная | По умолчанию | Описание |
| да | — | OAuth-токен Яндекс Метрики |
| нет |
| Таймаут HTTP-запросов к API (секунды) |
| нет |
| Таймаут скачивания файлов (секунды) |
Загрузка из файла
Вместо передачи переменных через -e можно указать файл:
mcp-server-yandex-metrika --env /path/to/.envФормат файла — KEY=VALUE, по одной переменной на строку, #-комментарии.
Работает в обоих режимах: MCP-сервер и CLI:
# MCP-сервер
claude mcp add yandex-metrika -- mcp-server-yandex-metrika --env ~/.config/metrika.env
# CLI
mcp-server-yandex-metrika --env ~/.config/metrika.env countersЛимиты API
30 запросов/секунду на IP
5000 запросов/день на пользователя
3 параллельных запроса на пользователя
200 запросов/5 минут для
/stat/v1/data/HTTP 420 при превышении лимитов
Разработка
pip install -e ".[test]"
ruff check src/ tests/
pytest tests/ -vЛицензия
MIT
Available Tools
12 toolsym_counterCRead-onlyIdempotent
Get counter details. field: goals,mirrors,grants,filters,operation.
Inputs: counter_id (required), field. Returns: result
ym_countersBRead-onlyIdempotent
List counters. Optional filters: search_string, permission (own/view/edit), status (Active/Deleted), per_page, offset.
Inputs: offset, status, per_page, permission, +1 more. Returns: result
ym_executeA
Execute action by ID. params_json validated against action schema. Use ym_search to discover actions and their schemas first.
Inputs: action (required), params_json. Returns: result
ym_execute_fileA
Execute action that reads or writes a file (uploads/downloads). file_path must be under ~/... or /tmp/... Use ym_search to discover file actions (is_file=true).
Inputs: action (required), file_path (required), params_json. Returns: result
ym_goalsBRead-onlyIdempotent
List goals for a counter.
Inputs: counter_id (required). Returns: result
ym_grantsCRead-onlyIdempotent
List access grants for a counter.
Inputs: counter_id (required). Returns: result
ym_labelsARead-onlyIdempotent
List all labels.
Inputs: no named parameters. Returns: result
ym_log_requestsBRead-onlyIdempotent
List log API requests for a counter.
Inputs: counter_id (required). Returns: result
ym_searchARead-only
Find available actions by intent. Optional domain filter: reporting, counters, goals, filters, grants, operations, segments, labels, accounts, delegates, annotations, access_filters, logs, uploads. Returns action ID, description, and JSON Schema of parameters.
Inputs: query (required), domain. Returns: result
ym_segmentsBRead-onlyIdempotent
List segments for a counter.
Inputs: counter_id (required). Returns: result
ym_stat_dataBRead-onlyIdempotent
Table report (GET /stat/v1/data). ids and metrics are comma-separated. Example: ids='12345', metrics='ym:s:visits,ym:s:users', dimensions='ym:s:browser', date1='7daysAgo', date2='today'.
Inputs: ids (required), metrics (required), sort, date1, +6 more. Returns: result
ym_stat_data_bytimeCRead-onlyIdempotent
Time-series report (GET /stat/v1/data/bytime). group: all/auto/minutes/hour/day/week/month/quarter/year.
Inputs: ids (required), metrics (required), date1, date2, +3 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Each tool has a clearly distinct purpose: search for actions, execute them, list specific resources (labels, counters, goals, etc.), and generate reports. There is no ambiguity between tools, and even similar report tools are differentiated by type.
All tools follow the 'ym_<resource_or_action>' pattern consistently. Names are descriptive and predictable, with only minor internal underscores (e.g., stat_data) which do not break the pattern.
12 tools is well-scoped for a Yandex Metrika server. It covers core resources (counters, goals, segments, etc.) and adds generic search/execute for extensibility without bloat.
The tool set covers all major Metrika operations with dedicated tools (counters, stats, goals, etc.) and provides a generic ym_execute for any remaining actions. This hybrid approach leaves no obvious gaps.
Maintenance
Related MCP Connectors
MCP servers for Yandex APIs: Wordstat, Search, Webmaster, Metrika, Direct. Open source, by Seyka AI.
Read-only Yandex Metrika MCP. Query visits, sources, geo, devices and more in plain language.
MCP server for querying and analyzing data from ad platforms, analytics tools, and spreadsheets
Cookie-free web analytics MCP server: read stats, create UTM links, goals and ad costs.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA Model Context Protocol (MCP) server that provides access to Yandex Metrika analytics data through various tools and functions. This server allows AI assistants and applications to retrieve comprehensive analytics data from Yandex Metrika accounts.1-
- AlicenseCqualityDmaintenanceMCP server for Yandex Metrika analytics, enabling AI assistants to access traffic, content, demographics, conversion, e-commerce, and drill-down reports.312MIT
- AlicenseAqualityBmaintenanceMCP server for Yandex Metrica analytics: query web analytics metrics, goals, conversions, and raw API data using natural language from AI clients like Claude and Cursor.8708 npm5MIT
- AlicenseAqualityCmaintenanceMCP server for Yandex.Metrica API providing 15 tools for managing counters, goals, reports, logs, traffic sources, and top pages with OAuth Bearer token authentication.15130 npm1MIT