Yandex Metrika

io.github.dontsovcmcPublished by GitHub account dontsovcmcv0.2.4Updated Oct 24, 2026

MCP server for Yandex Metrika API — counters, goals, reports, segments, logs

VerifiedSTDIODesktop onlyData & AnalyticsBusiness & Commerce

Overview

AI-generated overview

Local MCP server for the Yandex Metrika API that lets an assistant read analytics reports and manage counters, goals, segments, filters and log requests.

What you can do
Read reports: tabular, by-time, drill-down and segment/period comparison statistics for counters and metrics, plus chart annotations and access filters, operations, labels, accounts and delegates, and Logs API requests including evaluation, cancellation and TSV download, and offline conversions, calls, expenses and user parameters uploads, and create, update or delete counters, goals, filters, grants, segments, labels, operations, delegates and log requests.
When to use it
Useful when you work with Yandex Metrika and want an assistant to pull traffic and conversion statistics, inspect counters and goals, or set up and manage tracking objects and log exports without leaving the chat.
Requirements
Runs locally as a Python package (uvx or pip) on a desktop MCP client. Requires a Yandex Metrika OAuth token with metrika:read and metrika:write scopes, supplied in the YANDEX_METRIKA_TOKEN environment variable or an env file. Optional METRIKA_TIMEOUT and METRIKA_FILE_TIMEOUT variables. Network access to the Yandex Metrika API.
Before you install
The OAuth token grants read and write access to your Metrika account; store it carefully, for example in a separate env file rather than a shared config. Many tools create, update or delete counters, goals, filters, grants, segments, labels, delegates and log requests, and some upload conversion, call and expense data, so changes affect live analytics data. The API enforces rate limits (HTTP 420 when exceeded).

Installation

In SourceWeft

  1. Open Yandex Metrika in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

mcp-server-yandex-metrika

[Version]

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

  • MCP-сервер — интеграция с Claude Code, Claude Desktop и другими MCP-клиентами
  • CLI-утилита — работа с API из терминала, скрипты и автоматизация
  • Pydantic-модели — типизированные модели API для использования в своих Python-программах

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

Оглавление

Возможности

Отчёты (Reporting API)

ИнструментCLIОписание
ym_stat_datastat-dataТабличный отчёт по метрикам и измерениям
ym_stat_data_bytimestat-bytimeОтчёт по времени (группировка: час/день/неделя/месяц)
ym_stat_data_drilldownstat-drilldownDrill down отчёт с раскрытием уровней
ym_stat_data_comparisonstat-comparisonСравнение сегментов/периодов
ym_stat_data_comparison_drilldown—Сравнение с drill down

Счётчики

ИнструментCLIОписание
ym_counterscountersСписок счётчиков (поиск, фильтрация)
ym_countercounterИнформация о счётчике
ym_counter_createcounter-createСоздать счётчик
ym_counter_updatecounter-updateИзменить счётчик
ym_counter_deletecounter-deleteУдалить счётчик
ym_counter_undeletecounter-undeleteВосстановить удалённый

Цели

ИнструментCLIОписание
ym_goalsgoalsСписок целей счётчика
ym_goalgoalИнформация о цели
ym_goal_creategoal-createСоздать цель (url/number/step/action/...)
ym_goal_update—Изменить цель
ym_goal_deletegoal-deleteУдалить цель

Фильтры

ИнструментCLIОписание
ym_filtersfiltersСписок фильтров
ym_filter—Информация о фильтре
ym_filter_createfilter-createСоздать фильтр (IP, URL, реферер)
ym_filter_update—Изменить фильтр
ym_filter_deletefilter-deleteУдалить фильтр

Доступ (Grants)

ИнструментCLIОписание
ym_grantsgrantsСписок разрешений
ym_grant_creategrant-createВыдать разрешение
ym_grant_update—Изменить разрешение
ym_grant_deletegrant-deleteУдалить разрешение

Операции

ИнструментCLIОписание
ym_operationsoperationsСписок операций
ym_operation—Информация об операции
ym_operation_createoperation-createСоздать операцию (cut_parameter, to_lower, ...)
ym_operation_update—Изменить операцию
ym_operation_deleteoperation-deleteУдалить операцию

Сегменты

ИнструментCLIОписание
ym_segmentssegmentsСписок сегментов
ym_segment—Информация о сегменте
ym_segment_createsegment-createСоздать сегмент
ym_segment_update—Изменить сегмент
ym_segment_deletesegment-deleteУдалить сегмент

Метки

ИнструментCLIОписание
ym_labelslabelsСписок меток
ym_label_createlabel-createСоздать метку
ym_label_update—Изменить метку
ym_label_deletelabel-deleteУдалить метку
ym_counter_label_set—Привязать метку к счётчику
ym_counter_label_unset—Отвязать метку

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

ИнструментCLIОписание
ym_accountsaccountsСписок аккаунтов
ym_account_delete—Удалить аккаунт
ym_delegatesdelegatesСписок представителей
ym_delegate_adddelegate-addДобавить представителя
ym_delegate_deletedelegate-deleteУдалить представителя

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

ИнструментCLIОписание
ym_chart_annotationschart-annotationsСписок примечаний
ym_chart_annotation_createchart-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_requestslog-requestsСписок запросов логов
ym_log_request—Информация о запросе
ym_log_request_createlog-request-createСоздать запрос (hits/visits)
ym_log_request_evaluatelog-request-evaluateОценить возможность запроса
ym_log_request_clean—Очистить обработанные логи
ym_log_request_cancel—Отменить запрос
ym_log_request_downloadlog-downloadСкачать часть лога (TSV)

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

ИнструментCLIОписание
ym_offline_conversions_uploadupload-conversionsЗагрузить оффлайн-конверсии
ym_offline_conversions_uploads—Список загрузок конверсий
ym_offline_conversion_upload_info—Инфо о загрузке
ym_calls_uploadupload-callsЗагрузить звонки
ym_calls_uploads—Список загрузок звонков
ym_calls_upload_info—Инфо о загрузке звонков
ym_expenses_uploadupload-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 — если не установлен:

bash
curl -LsSf https://astral.sh/uv/install.sh | sh
bash
claude mcp add yandex-metrika \  -e YANDEX_METRIKA_TOKEN=ваш_токен \  -- uvx mcp-server-yandex-metrika

Способ 2: через pip

bash
pip install mcp-server-yandex-metrika
claude mcp add yandex-metrika \  -e YANDEX_METRIKA_TOKEN=ваш_токен \  -- mcp-server-yandex-metrika

Для удаления:

bash
claude mcp remove yandex-metrika

Подключение к Claude Desktop

Добавьте в конфигурационный файл:

КлиентОСПуть к файлу
Claude Codeвсе~/.claude/settings.json (секция mcpServers)
Claude DesktopmacOS~/Library/Application Support/Claude/claude_desktop_config.json
Claude DesktopWindows%APPDATA%\Claude\claude_desktop_config.json
Claude DesktopLinux~/.config/Claude/claude_desktop_config.json

Через uvx:

json
{  "mcpServers": {    "yandex-metrika": {      "command": "uvx",      "args": ["mcp-server-yandex-metrika"],      "env": {        "YANDEX_METRIKA_TOKEN": "ваш_токен"      }    }  }}

Через pip (после pip install mcp-server-yandex-metrika):

json
{  "mcpServers": {    "yandex-metrika": {      "command": "python",      "args": ["-m", "mcp_server_yandex_metrika"],      "env": {        "YANDEX_METRIKA_TOKEN": "ваш_токен"      }    }  }}

Подключение через --mcp-config

Подключает сервер только на время одной сессии Claude, не сохраняя в настройки. Токен хранится в отдельном .env.mcp файле, а не в конфиге Claude.

Из JSON-строки:

bash
claude --mcp-config '{"yandex-metrika":{"command":"bash","args":["-c","source ~/.env.mcp && exec uvx mcp-server-yandex-metrika"]}}'

Из файла:

bash
claude --mcp-config ~/mcp-servers.json

Пример ~/mcp-servers.json:

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)

bash
pip install mcp-server-yandex-metrika

Переменная окружения YANDEX_METRIKA_TOKEN должна быть установлена:

bash
export YANDEX_METRIKA_TOKEN=ваш_токен

Или через файл:

bash
mcp-server-yandex-metrika --env /path/to/.env counters

Формат файла — KEY=VALUE, по одной переменной на строку, #-комментарии.

Использование (CLI)

Без аргументов запускается MCP-сервер, с командой — CLI. Все команды выводят JSON.

bash
# Версияmcp-server-yandex-metrika --version
# Справкаmcp-server-yandex-metrika --helpmcp-server-yandex-metrika <command> --help

Примеры команд

bash
# Статистика визитов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.

Установка (библиотеки)

bash
pip install mcp-server-yandex-metrika

Использование в своих программах

python
from mcp_server_yandex_metrika.models import CounterBrief, Goal
# Валидация данных из APIdata = {"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 можно указать файл:

bash
mcp-server-yandex-metrika --env /path/to/.env

Формат файла — KEY=VALUE, по одной переменной на строку, #-комментарии.

Работает в обоих режимах: MCP-сервер и CLI:

bash
# MCP-серверclaude mcp add yandex-metrika -- mcp-server-yandex-metrika --env ~/.config/metrika.env
# CLImcp-server-yandex-metrika --env ~/.config/metrika.env counters

Лимиты API

  • 30 запросов/секунду на IP
  • 5000 запросов/день на пользователя
  • 3 параллельных запроса на пользователя
  • 200 запросов/5 минут для /stat/v1/data/
  • HTTP 420 при превышении лимитов

Разработка

bash
pip install -e ".[test]"ruff check src/ tests/pytest tests/ -v

Лицензия

MIT

Source: README.md at commit cd20e21

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.2.4LatestSep 16, 2026

Score

40% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

    Declare a license in the repository or the registry entry.