Yandex Metrika

mcp-server-yandex-metrika

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

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

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

Оглавление

• Возможности
• MCP-сервер
• Установка
• Подключение к Claude Code
• Подключение к Claude Desktop
• Подключение через --mcp-config
• Примеры
• CLI-утилита
• Установка
• Использование
• Примеры команд
• Pydantic-модели
• Установка
• Использование в своих программах
• Переменные окружения
• Лимиты API
• Разработка
• Лицензия

Возможности

Отчёты (Reporting API)

Счётчики

Цели

Фильтры

Доступ (Grants)

Операции

Сегменты

Метки

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

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

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

Logs API

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

---

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

`

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

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

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

---

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

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

Вместо передачи переменных через -e можно указать файл:

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

Формат фай