Umami MCP Server

MCP-сервер только для чтения для аналитики Umami. Он взаимодействует с REST API Umami напрямую по HTTP, в первую очередь поддерживает self-hosted установки Umami, а также работает с ключами API Umami Cloud.

Этот репозиторий создан для того, чтобы агенты верхнего уровня могли запрашивать аналитику, не перечитывая документацию Umami каждый раз. Никакой автоматизации браузера, никакого парсинга DOM, никаких операций записи.

Возможности

• Инструменты MCP только для чтения для наиболее распространенных запросов аналитики Umami

• Два режима аутентификации:

  • UMAMI_API_KEY

  • UMAMI_USERNAME + UMAMI_PASSWORD

• Кэширование bearer-токена в памяти для self-hosted установок

• Автоматический повторный вход и одна попытка повтора при 401 для режима с именем пользователя/паролем

• Поддержка как ISO-строк времени, так и временных меток в миллисекундах

• Общая обработка фильтров для статистики, просмотров страниц, разбивок и серий событий

• Строгий TypeScript с небольшими, поддерживаемыми модулями

• Четкий структурированный вывод инструментов и явные категории ошибок

Требования

• Node.js >= 20

• pnpm >= 10

Установка

Из npm:

npm install -g umami-analytics-mcp

Или запуск без установки:

npx -y umami-analytics-mcp

Для локальной разработки в этом репозитории:

pnpm install

Настройка

Создайте файл .env на основе .env.example.

cp .env.example .env

Заполните один из следующих вариантов аутентификации:

1. Режим API-ключа

UMAMI_API_URL=https://api.umami.is/v1
UMAMI_API_KEY=your-api-key
UMAMI_DEFAULT_TIMEZONE=Asia/Shanghai

2. Режим имени пользователя/пароля для self-hosted

UMAMI_API_URL=https://umami.example.com/api
UMAMI_USERNAME=admin
UMAMI_PASSWORD=secret
UMAMI_DEFAULT_TIMEZONE=Asia/Shanghai

Примечания:

• UMAMI_API_URL должен указывать на базу API, а не просто на источник сайта.

• Если установлены и UMAMI_API_KEY, и имя пользователя/пароль, UMAMI_API_KEY имеет приоритет.

• UMAMI_DEFAULT_TIMEZONE используется, когда инструмент поддерживает часовой пояс, а вы его не указали.

Локальный запуск

Режим разработки:

pnpm dev

Сборка и запуск:

pnpm build
pnpm start

Сервер использует транспорт MCP stdio, поэтому он остается подключенным к stdin/stdout до тех пор, пока клиент не отключится.

Если установлено из npm, эквивалентная команда:

umami-analytics-mcp

Тестирование

pnpm test
pnpm build

Также существует шаблон интеграционного теста с реальным API, который по умолчанию пропускается:

UMAMI_INTEGRATION_TEST=1 pnpm test:integration

MCP Inspector

Сначала выполните сборку:

pnpm build

Затем запустите официальный MCP Inspector для собранного сервера:

npx @modelcontextprotocol/inspector node dist/cli.js

Для горячей перезагрузки во время разработки это также работает:

npx @modelcontextprotocol/inspector pnpm dev

Если вы хотите протестировать путь к опубликованному пакету, используйте:

npx @modelcontextprotocol/inspector npx -y umami-analytics-mcp

Убедитесь, что те же переменные окружения Umami доступны процессу Inspector.

Рекомендуемые дымовые тесты в Inspector:

1. umami_ping

2. umami_list_websites

3. umami_get_stats

4. umami_get_breakdown

Инструменты

umami_ping

Проверяет конфигурацию и аутентификацию.

Пример:

{}

umami_list_websites

Выводит список доступных веб-сайтов.

Пример:

{}

umami_find_website

Нечеткий поиск по названию или домену веб-сайта.

Пример:

{
  "query": "example.com"
}

umami_get_stats

Сводная статистика для веб-сайта и временного диапазона.

Пример:

{
  "websiteId": "8f2f8ce2-1234-4567-89ab-0123456789ab",
  "startAt": "2026-04-23T00:00:00+08:00",
  "endAt": "2026-04-23T23:59:59+08:00",
  "filters": {
    "path": "/pricing"
  }
}

umami_get_pageviews

Временные ряды просмотров страниц и сессий.

Пример:

{
  "websiteId": "8f2f8ce2-1234-4567-89ab-0123456789ab",
  "startAt": "2026-04-17T00:00:00+08:00",
  "endAt": "2026-04-23T23:59:59+08:00",
  "unit": "day",
  "compare": "prev",
  "filters": {
    "path": "/blog"
  }
}

umami_get_breakdown

Строки разбивки, такие как популярные страницы, источники переходов, страны, браузеры, устройства и многое другое.

Пример:

{
  "websiteId": "8f2f8ce2-1234-4567-89ab-0123456789ab",
  "startAt": "2026-04-17T00:00:00+08:00",
  "endAt": "2026-04-23T23:59:59+08:00",
  "type": "path",
  "limit": 10,
  "expanded": false
}

umami_get_active

Возвращает текущее количество активных посетителей.

Пример:

{
  "websiteId": "8f2f8ce2-1234-4567-89ab-0123456789ab"
}

umami_get_events_series

Возвращает количество пользовательских событий во времени.

Пример:

{
  "websiteId": "8f2f8ce2-1234-4567-89ab-0123456789ab",
  "startAt": "2026-04-17T00:00:00+08:00",
  "endAt": "2026-04-23T23:59:59+08:00",
  "unit": "day"
}

Общие фильтры

Эти инструменты поддерживают один и тот же объект filters:

• path

• referrer

• title

• query

• browser

• os

• device

• country

• region

• city

• hostname

Обработка ошибок

Ошибки инструментов возвращаются как структурированные результаты MCP-инструментов со следующими категориями:

• config_missing

• auth_failed

• website_not_found

• umami_http_error

• network_timeout

• network_error

• invalid_input

Подключение в любом Stdio MCP-клиенте

Любой MCP-клиент на базе stdio может запустить этот сервер с помощью:

• command: npx

• args: ["-y", "umami-analytics-mcp"]

• env: ваши переменные Umami

Пример фрагмента JSON для клиентов, использующих объект mcpServers:

{
  "mcpServers": {
    "umami": {
      "command": "npx",
      "args": ["-y", "umami-analytics-mcp"],
      "env": {
        "UMAMI_API_URL": "https://umami.example.com/api",
        "UMAMI_USERNAME": "admin",
        "UMAMI_PASSWORD": "secret",
        "UMAMI_DEFAULT_TIMEZONE": "Asia/Shanghai"
      }
    }
  }
}

Для локальной невыпущенной версии вы все равно можете указать путь напрямую к собранному файлу:

{
  "mcpServers": {
    "umami": {
      "command": "node",
      "args": ["/absolute/path/to/umami-mcp/dist/cli.js"]
    }
  }
}

Публикация в npm

Этот репозиторий теперь структурирован как CLI-пакет npm.

Рекомендуемый процесс выпуска:

pnpm test
pnpm build
pnpm pack --dry-run
npm login
pnpm publish

Примечания:

• Имя пакета установлено как umami-analytics-mcp, так как umami-mcp уже занято в npm.

• Текущая license — UNLICENSED в качестве безопасного заполнителя. Замените ее перед реальным публичным open-source релизом, если хотите использовать разрешительную лицензию.

• Если позже вы будете публиковать пакет под своим собственным пространством имен npm, измените только поле name в package.json.

Внутренняя документация

• Сводка API, используемая этим репозиторием: docs/umami-api.md