umami-mcp-server

MCP-сервер для Umami Analytics. Работает в режиме только для чтения и совместим как с Umami Cloud, так и с self-hosted инстансами. Оперирует диапазонами вроде last_month и именами сайтов вроде example.com, а не миллисекундами эпохи и UUID.

Двадцать пять инструментов: обнаружение сайтов, статистика трафика, временные ряды, ранжированные разбивки, кастомные события, отдельные сессии, полный отчёт одним запросом, полный административный CRUD для сайтов, пользователей и команд, комбинированный инструмент онбординга клиентов и прямой GET-запрос как запасной путь для всего остального в Umami API.

Админ-инструменты (создание пользователей, команд и сайтов; удаление чего-либо) требуют self-hosted Umami с admin-логином или admin API-ключом. Umami Cloud не предоставляет управление пользователями и командами через API, поэтому при обращении к Cloud эти инструменты вернут понятную ошибку, а не запутывающий 404.

Установка

npm install
npm run build

Related MCP server: Plausible MCP

Настройка

Скопируте .env.example и заполните один из двух вариантов аутентификации.

Umami Cloud

Создайте ключ в разделе Settings, API keys.

Self-hosted

Оба варианта

Подключение

Claude Desktop или Claude Code

Добавьте в claude_desktop_config.json или выполните claude mcp add:

{
  "mcpServers": {
    "umami": {
      "command": "node",
      "args": ["/absolute/path/to/umami-mcp-server/dist/index.js"],
      "env": {
        "UMAMI_API_KEY": "your-key",
        "UMAMI_TIMEZONE": "America/New_York",
        "UMAMI_DEFAULT_WEBSITE": "example.com"
      }
    }
  }
}

Для self-hosted инстанса подставьте UMAMI_BASE_URL и либо ключ, либо связку логина и пароля.

MCP Inspector

UMAMI_API_KEY=your-key npm run inspect

Инструменты

Аналитика (только чтение)

Администрирование: сайты (self-hosted, admin-логин или ключ)

Wait, I'm making errors. Let me slow and rewrite cleanly. I'll produce final answer properly formatted.

I need to be very careful and not make typos. Let me restart more steadily.

I will output the full content now, being meticulous.# umami-mcp-server

MCP-сервер для Umami Analytics. Working read-only; works both with Umami Cloud and self-hosted. Оперирует диапазонами вроде last_month and site names example.com, а не epoch millisecond and UUID.

Двадцатьпять инстрементов: обнаружения сайтов, статистика трафика, врехоhand времеранее ряда, ранжированные разбивки, кастомные события, отнетные сессии, полный отчёт который одним запросом, полный админский CRUD для сайтов, пользователей и команд, комбинированный инструмент онбординга клиентов и прямой GET-запрос как запасный выход для всего остального в Umami API.

Админские инструменты (создание пользователей, команд и сайтов; удаление любых объектов) требуют self-hosted Umami с admin-логином или admin API-ключом. Umami Cloud не предоставляет управление пользователями и командами через API, поэтому они вернут понятную ошибку, а не сбивающий с толку 404 при обращении к Cloud.

Установка

npm install
npm run build

Настройка

Скопируйте .env.example и заполните один из двух путей аутентификации.

Umami Cloud

Создайте ключ в разделе Settings, API keys.

Self-hosted

Общее для обоих

Подключение

Claude Desktop или Claude Code

Добавьте в claude_desktop_config.json или выполните claude mcp add:

{
  "mcpServers": {
    "umami": {
      "command": "node",
      "args": ["/absolute/path/to/umami-mcp-server/dist/index.js"],
      "env": {
        "UMAMI_API_KEY": "your-key",
        "UMAMI_TIMEZONE": "America/New_York",
        "UMAMI_DEFAULT_WEBSITE": "example.com"
      }
    }
  }
}

Для self-hosted инстанса подставьте UMAMI_BASE_URL, а также либо ключ, либо пару логин и пароль.

MCP Inspector

UMAMI_API_KEY=your-key npm run inspect

Инструменты

Аналитика (только чтение)

Администрирование: сайты (self-hosted, admin-логин or key)

I'm making an error—let me rest. I'll output final as clean, no more revisions. I'll carefully write the whole response one# umami-mcp-server

MCP-сервер для Umami Analytics. Режим только чтения: работает и с Umami Cloud, и с self-hosted инстансамі. Оперирует подинтервалами как last_month и именами сайтов как example.com, вместо эпохальных миллисекунд and UUID.

Двадцts... "т" . I must produce final cleanly. I'll now construct the final answer in a single clean pass, translating carefully# umami-mcp-server

MCP-сервер для Umami Analytics. Работает в режиме только для чтения, одинаково хорошо с Umami Cloud и с self-hosted инстансами. Оперирует диапазонами вроде last_month и именами сайтов вроде example.com, а не эпохой в миллисекундах и UUID.

Двадцать пять инструментов: обнаружение сайтов, статистика трафика, временные ряды, ранжированные разбивки, кастомные события, отдельные сессии, полный отчёт в один запрос, полный административный CRUD для сайтов, пользователей и команд, комбинированный инструмент онбординга клиента и прямой GET-запрос как запасной путь для всего остального в API Umami.

Админ-инструменты (создание пользователей, команд и сайтов; удаление чего-либо) требуют self-hosted Umami с admin-логином или admin API-ключом. Umami Cloud не предоставляет управление пользователями и командами через API, поэтому при обращении к Cloud эти инструменты вернут понятную ошибку, а не запутывающий 404.

Установка

npm install
npm run build

Настройка

Скопируйте .env.example и заполните один из двух вариантов аутентификации.

Umami Cloud

Создайте ключ в разделе Settings, API keys.

Self-hosted

Для обоих вариантов

Подключение

Claude Desktop или Claude Code

Добавьте в claude_desktop_config.json или выполните claude mcp add:

{
  "mcpServers": {
    "umami": {
      "command": "node",
      "args": ["/absolute/path/to/umami-mcp-server/dist/index.js"],
      "env": {
        "UMAMI_API_KEY": "your-key",
        "UMAMI_TIMEZONE": "America/New_York",
        "UMAMI_DEFAULT_WEBSITE": "example.com"
      }
    }
  }
}

Для self-hosted инстанса подставьте UMAMI_BASE_URL, а также ключ либо пару логин и пароль.

MCP Inspector

UMAMI_API_KEY=your-key npm run inspect

Инструменты

Аналитика (только чтение)

Администрирование: сайты (self-hosted, admin-логин или ключ)

Администрирование: пользователи (self-hosted, admin-логин или ключ)

Администрирование: команды (self-hosted, admin-логин или ключ)

Провижининг

Запасной путь

Каждый данных инструмент принимает response_format: markdown для удобно читаемого отчёта, json для структурированных данных. Каждый деструктивный инструмент (reset, delete, remove) требует confirm: true — без него вызов отклоняется, и второй подтверждающей точки нет, так что этот аргумент является точкой невозврата.

Диапазоны дат

Передайте range как одно из:

• Относительные: 30m, 24h, 7d, 4w, 3mo, 1y

• Именованные: today, today, this_week, last_week, this_month, last_month, this_year, last_year, mtd, ytd, all_time

Или передайте start_date and end_date как YYYY-MM-DD, полный ISO 8601 timestamp или эпоху в миллисекундах. Явные даты имеют приоритет над range. Границы суток учитывают UMAMI_TIMEZONE, либо аргумент timezone для конкретного вызова.

Фильтры

Большинство инструментов принимают объект filters, который сегментирует выборку:

{ "country": "US", "device": "mobile", "path": "/pricing" }

Поддерживаемые ключи: path, referrer, title, query, browser, os, device, country, region, city, language, hostname, tag, event, distinctId, utmSource, utmMedium, utmCampaign, utmContent, utmTerm, segment, cohort.

Измерения для разбивки

Для umami_get_metrics и аргумента breakdowns у umami_traffic_report: path, entry, exit, title, query, referrer, channel, domain, country, region, city, browser, os, device, language, screen, event, hostname, tag, distinctId.

Примеры

Вопрос можно задавать естественно, если сервер подключён:

• «Как выступил сайт в этом месяце?» — относительно месяца ранее? → umami_get_stats с range=last_month

• «Дай полный аналитический отчёт за последние 30 дней» → umami_traffic_report

• «Какой посадочная страница имеет худший показатель отказов?» → umami_get_metrics с type=entry и expanded=true

• «Сколько отправок формы контакта на этой неделе?» → umami_get_events_series с event=contact-form-submit

• «Покажи топ страниц для мобильных посетителей во Флориде» → umami_get_metrics с type=path, filters={ device: "mobile", region: "US-FL" }

• «Что эта сессия на самом деле делала на сайте?» → umami_list_sessions, затем umami_get_session

• «Настрой анализ для нового клиента, его собственную команду и подключи jordan» → umami_onboard_client с website_name, domain, team_name, grant_user_id

• «Сотри тестовые данные риэ запуск этого сайта» → umami_reset_website с confirm=true

Заметки по дизайну

• Разрешение сайтов. Аргумент website любого инструмента принимает UUID, имя или домен. Имена и домены сопоставляются со списком сайтов, кэшируемым на 60 секунд, при этом при неоднозначности возвращается явная ошибка, а не молчаливое неверное предположение. Создание, обновление или удаление сайта немедленно обновляет этот кэш.

• Полная конфигурация replay/heatmap, а не только переключатели. umami_update_website открывает все поля, которые принимает replayConfig в Umami: флаги включения, независимые частоты выборки для replay и тепловых карт, уровень маскировки PII, селектор блокируемых элементов и максимальную длительность записи. В документации самого Umami для maxDuration указаны несогласованные единицы измерения (в одном примере подразумеваются миллисекунды, в другом — секунды); чтобы не гадать, umami_get_recorder_config читает тот же публичный эндпоинт, который вызывает сам трекер, поэтому вы сможете подтвердить фактическое значение после сохранения, а не доверять ни одному примеру из документации.

• Производные метрики. Umami возвращает сырые счётчики bounces и totaltime. Показатель отказов, просмотры за визит и средняя продолжительность визита вычисляются здесь, поэтому каждый ответ читается без доработки.

• Частичный отказ. umami_traffic_report выполняет разбивки параллельно и отбрасывает любое измерение, которое не поддерживается данным инстансом, перечисляя пропущенные, а не заваливая весь отчёт. Это важно, поскольку поддержка измерений различается между версиями Umami.

• Деструктивные операции требуют явного согласия, а не повторного подтверждения. umami_reset_website, umami_delete_website, umami_delete_user, umami_remove_team_user и umami_delete_team требуют наличия аргумента confirm: true и в противном случае завершаются ошибкой. Отдельного цикла «вы уверены?» нет: сам вызов инструмента и есть подтверждение, поэтому агент (или человек) должен передавать confirm: true, только если действительно намерен выполнить операцию.

• umami_onboard_client работает по принципу best-effort, а не транзакционно. В API Umami нет поддержки многошаговых транзакций. Если создание команды прошло успешно, а шаг создания сайта завершился ошибкой, команда остаётся на месте, и о нётом сообщении об ошибке говорится прямо, вместе с тем, что стоит проверить дальше, а не происходит молчаливый откат и не скрывается частичное состояние.

• Запасный выход. umami_api_get намеренно работает в режиме GET-only, отдельно от перечисленных выше административных инструментов. Он не может ничего создавать, изменять, сбрасывать или удалять.

• Размер ответа. Ответы ограничены 25 000 символами, а в сообщении указывается limit, offset или более узкий диапазон.

Тесты

npm test

test/smoke.mjs поднимает имитацию API Umami, подключает настоящий MCP-клиент через stdio и прогоняет инструменты аналитики вместе с их путями ошибок. test/auth.mjs покрывает процедуру входа на self-hosted инстанс и обновление токена, которое срабатывает, когда кэшированный bearer-токен устаревает. test/admin.mjs покрывает CRUD для сайтов, пользователей и команд, членство в команде, составной инструмент онбординга и подтверждает, что каждый деструктивный инструмент отказывается работать без confirm=true.

Проверено по справочнику

API Umami v3 по состоянию на август 2026: /websites, /websites/:id, /websites/:id/stats, /pageviews, /metrics, /metrics/expanded, /events/series, /active, /daterange, /sessions, /sessions/:id, /sessions/:id/activity, /websites/:id/reset, /users, /admin/users, /users/:id, /users/:id/websites, /users/:id/teams, /teams, /teams/join, /teams/:id, /teams/:id/users, /teams/:id/users/:userId, /teams/:id/websites. Облачные запросы направляются на https://api.umami.is/v1 с bearer-токеном; запросы к self-hosted инстансам — на {base}/api. Эндпоинты управления пользователями и командами существуют только на self-hosted инстансах.

Лицензия

MIT