yandex-metrika

mcp-server-yandex-metrika

API Яндекс Метрики向けの MCP サーバー、CLI ツール、Pydantic モデルライブラリです。

• MCP サーバー — Claude Code、Claude Desktop、その他の MCP クライアントとの連携
• CLI ツール — ターミナルからの API 利用、スクリプト、オートメーション
• Pydantic モデル — 独自の Python プログラムで利用できる、型付き API モデル

すべてのデータはお使いのコンピューターに保存され、トークンが外部に送信されることはありません。

目次

• 機能
• MCP サーバー
  • インストール
  • Claude Code への接続
  • Claude Desktop への接続
  • --mcp-config を使用した接続
  • 例
• CLI ツール
  • インストール
  • 使い方
  • コマンド例
• Pydantic モデル
  • ライブラリのインストール
  • 独自プログラムでの使用
• 環境変数
• API の制限
• 開発
• ライセンス

機能

レポート（Reporting API）

ツール	CLI	説明
ym_stat_data	stat-data	指標とディメンションの表形式レポート
ym_stat_data_bytime	stat-bytime	時系列レポート（グループ化：時間／日／週／月）
ym_stat_data_drilldown	stat-drilldown	階層を展開するドリルダウンレポート
ym_stat_data_comparison	stat-comparison	セグメント／期間の比較
ym_stat_data_comparison_drilldown	—	ドリルダウンによる比較

カウンター

ツール	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	—	フィルターを削除

アクセス権（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