Skip to main content
Glama
io.github.dontsovcmc/yandex-metrika

io.github.dontsovcmc/yandex-metrika

by dontsovcmc

mcp-server-yandex-metrika

Version

MCP-сервер, CLI-утилита и библиотека Pydantic-моделей для API Яндекс Метрики.

  • MCP-сервер — интеграция с Claude Code, Claude Desktop и другими MCP-клиентами

  • CLI-утилита — работа с API из терминала, скрипты и автоматизация

  • Pydantic-модели — типизированные модели API для использования в своих Python-программах

Все данные остаются на вашем компьютере — токен никуда не передаётся.

Оглавление

Related MCP server: ya-metrics-mcp

Возможности

Отчёты (Reporting API)

Инструмент

CLI

Описание

ym_stat_data

stat-data

Табличный отчёт по метрикам и измерениям

ym_stat_data_bytime

stat-bytime

Отчёт по времени (группировка: час/день/неделя/месяц)

ym_stat_data_drilldown

stat-drilldown

Drill down отчёт с раскрытием уровней

ym_stat_data_comparison

stat-comparison

Сравнение сегментов/периодов

ym_stat_data_comparison_drilldown

—

Сравнение с drill down

Счётчики

Инструмент

CLI

Описание

ym_counters

counters

Список счётчиков (поиск, фильтрация)

ym_counter

counter

Информация о счётчике

ym_counter_create

counter-create

Создать счётчик

ym_counter_update

counter-update

Изменить счётчик

ym_counter_delete

counter-delete

Удалить счётчик

ym_counter_undelete

counter-undelete

Восстановить удалённый

Цели

Инструмент

CLI

Описание

ym_goals

goals

Список целей счётчика

ym_goal

goal

Информация о цели

ym_goal_create

goal-create

Создать цель (url/number/step/action/...)

ym_goal_update

—

Изменить цель

ym_goal_delete

goal-delete

Удалить цель

Фильтры

Инструмент

CLI

Описание

ym_filters

filters

Список фильтров

ym_filter

—

Информация о фильтре

ym_filter_create

filter-create

Создать фильтр (IP, URL, реферер)

ym_filter_update

—

Изменить фильтр

ym_filter_delete

filter-delete

Удалить фильтр

Доступ (Grants)

Инструмент

CLI

Описание

ym_grants

grants

Список разрешений

ym_grant_create

grant-create

Выдать разрешение

ym_grant_update

—

Изменить разрешение

ym_grant_delete

grant-delete

Удалить разрешение

Операции

Инструмент

CLI

Описание

ym_operations

operations

Список операций

ym_operation

—

Информация об операции

ym_operation_create

operation-create

Создать операцию (cut_parameter, to_lower, ...)

ym_operation_update

—

Изменить операцию

ym_operation_delete

operation-delete

Удалить операцию

Сегменты

Инструмент

CLI

Описание

ym_segments

segments

Список сегментов

ym_segment

—

Информация о сегменте

ym_segment_create

segment-create

Создать сегмент

ym_segment_update

—

Изменить сегмент

ym_segment_delete

segment-delete

Удалить сегмент

Метки

Инструмент

CLI

Описание

ym_labels

labels

Список меток

ym_label_create

label-create

Создать метку

ym_label_update

—

Изменить метку

ym_label_delete

label-delete

Удалить метку

ym_counter_label_set

—

Привязать метку к счётчику

ym_counter_label_unset

—

Отвязать метку

Аккаунты и представители

Инструмент

CLI

Описание

ym_accounts

accounts

Список аккаунтов

ym_account_delete

—

Удалить аккаунт

ym_delegates

delegates

Список представителей

ym_delegate_add

delegate-add

Добавить представителя

ym_delegate_delete

delegate-delete

Удалить представителя

Примечания на графике

Инструмент

CLI

Описание

ym_chart_annotations

chart-annotations

Список примечаний

ym_chart_annotation_create

chart-annotation-create

Создать примечание

ym_chart_annotation_update

—

Изменить примечание

ym_chart_annotation_delete

—

Удалить примечание

Фильтры доступа

Инструмент

CLI

Описание

ym_access_filters

—

Список фильтров доступа

ym_access_filter_create

—

Создать фильтр доступа

ym_access_filter_update

—

Изменить фильтр доступа

ym_access_filter_delete

—

Удалить фильтр доступа

Logs API

Инструмент

CLI

Описание

ym_log_requests

log-requests

Список запросов логов

ym_log_request

—

Информация о запросе

ym_log_request_create

log-request-create

Создать запрос (hits/visits)

ym_log_request_evaluate

log-request-evaluate

Оценить возможность запроса

ym_log_request_clean

—

Очистить обработанные логи

ym_log_request_cancel

—

Отменить запрос

ym_log_request_download

log-download

Скачать часть лога (TSV)

Импорт данных

Инструмент

CLI

Описание

ym_offline_conversions_upload

upload-conversions

Загрузить оффлайн-конверсии

ym_offline_conversions_uploads

—

Список загрузок конверсий

ym_offline_conversion_upload_info

—

Инфо о загрузке

ym_calls_upload

upload-calls

Загрузить звонки

ym_calls_uploads

—

Список загрузок звонков

ym_calls_upload_info

—

Инфо о загрузке звонков

ym_expenses_upload

upload-expenses

Загрузить расходы

ym_user_params_upload

—

Загрузить параметры пользователей


MCP-сервер

Установка

Шаг 1. Получить OAuth-токен Яндекс Метрики

  1. Зарегистрируйте приложение на oauth.yandex.com

  2. Укажите права: metrika:read, metrika:write

  3. Получите токен: 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/settings.json (секция mcpServers)

Claude Desktop

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

Claude Desktop

Windows

%APPDATA%\Claude\claude_desktop_config.json

Claude Desktop

Linux

~/.config/Claude/claude_desktop_config.json

Через 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 visits

Pydantic-модели

Пакет содержит типизированные 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


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

Переменная

Обязательная

По умолчанию

Описание

YANDEX_METRIKA_TOKEN

да

—

OAuth-токен Яндекс Метрики

METRIKA_TIMEOUT

нет

30

Таймаут HTTP-запросов к API (секунды)

METRIKA_FILE_TIMEOUT

нет

60

Таймаут скачивания файлов (секунды)

Загрузка из файла

Вместо передачи переменных через -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 tools
ym_counterC
Read-onlyIdempotent

Get counter details. field: goals,mirrors,grants,filters,operation.

Inputs: counter_id (required), field. Returns: result

ym_countersB
Read-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_goalsB
Read-onlyIdempotent

List goals for a counter.

Inputs: counter_id (required). Returns: result

ym_grantsC
Read-onlyIdempotent

List access grants for a counter.

Inputs: counter_id (required). Returns: result

ym_labelsA
Read-onlyIdempotent

List all labels.

Inputs: no named parameters. Returns: result

ym_log_requestsB
Read-onlyIdempotent

List log API requests for a counter.

Inputs: counter_id (required). Returns: result

ym_segmentsB
Read-onlyIdempotent

List segments for a counter.

Inputs: counter_id (required). Returns: result

ym_stat_dataB
Read-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_bytimeC
Read-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

    A3.6/5.0

    Scored across 12 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      A 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
      -
    • A
      license
      A
      quality
      B
      maintenance
      MCP 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.
      8
      708 npm
      5
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      MCP server for Yandex.Metrica API providing 15 tools for managing counters, goals, reports, logs, traffic sources, and top pages with OAuth Bearer token authentication.
      15
      130 npm
      1
      MIT