Umami MCP Server

A Model Context Protocol server for Umami Analytics. Ask Claude, Cursor or any MCP client about your traffic — and let it create and manage websites — while your credentials stay on your own machine.

"Which pages drove the most visitors last month, and where did that traffic come from?"
"Build a funnel from /pricing to /signup to /welcome for the last 30 days."
"Add analytics for my new site blog.example.com and give me the tracking snippet."

Зачем это существует

У Umami нет официального MCP-сервера. Существует несколько серверов от сообщества, и если вам нужен просто широкий охват API, сначала стоит посмотреть на 0xtlt/umami-mcp — он оборачивает больше API, чем этот. Некоторые старые серверы (jakeyShakey, mikusnuz, mittwald, Macawls) были написаны под API v2 и ломаются на современном инстансе, потому что v3 переименовала вещи без алиасов:

Этот сервер существует для двух вещей, которые другие не делают:

1. Полное проверенное покрытие отчётов v3. Все семь типов отчётов v3 — воронка, удержание, путь, цель, выручка, атрибуция и UTM — были опробованы на живом инстансе Umami 3.3.1. Структуру отчёта легко испортить: даты помещаются в parameters как ISO-8601 строки, а не в filters и не как миллисекунды эпохи, которые использует остальной API. Атрибуция принимает first-click / last-click, а не варианты в camelCase, которые вы бы предположили.

2. Модель возможностей, а не булево значение. См. ниже.

Related MCP server: Umami MCP Server

Модель безопасности

MCP-сервер аналитики хранит учётные данные, которые могут прочитать каждую сессию посетителя, когда-либо записанную вами, — и, если вы позволите, удалить их все. Дизайн следует из этого.

Ваши учётные данные никогда не покидают ваше окружение. Конфигурация читается только из окружения процесса. Никакой телеметрии, никаких звонков домой и никакого размещённого ретранслятора. Единственный хост, с которым этот сервер когда-либо связывается, — это UMAMI_URL, который вы задали. Если вы размещаете его самостоятельно, ничто из вашей аналитики никогда не попадает к третьим лицам — включая автора этого программного обеспечения.

Остерегайтесь любого Umami MCP, который предлагает размещённую конечную точку, на которую вы указываете свой инстанс. Самостоятельно размещённый Umami не имеет API-ключей, поэтому «удобный» хостинг означает отправку вашего пароля администратора на чужой сервер.

Наименьшие привилегии по умолчанию. Сервер запускается в режиме read. Расширение прав — это обдуманное действие:

Скрытые инструменты вообще не регистрируются, поэтому они никогда не появляются в списке инструментов модели. Именно это отличает данный подход от флага READONLY=true: инструмент, который никогда не анонсировался, не может быть вызван инструкцией, внедрённой через промпт и спрятанной, скажем, в строке реферера или заголовке страницы внутри ваших собственных данных аналитики. Не существует проверки во время выполнения, которую можно забыть или обойти, потому что нет инструмента.

Разрушительные действия требуют текстового подтверждения, сверяемого с реальностью. umami_delete_website принимает аргумент confirmDomain, получает актуальную запись и отказывается, если они не совпадают. Модель, которая обращается не к тому UUID веб-сайта, получает ошибку, а не стёртый набор данных.

Учётные данные не попадают в конфиг клиента. Вместо требования вашего пароля внутри ~/.claude.json или mcp.json, сервер читает его из файла, которым вы управляете, по пути ~/.config/umami-mcp/env, и предупреждает, если этот файл доступен для чтения другим пользователям. См. Учётные данные.

Секреты вычищаются из вывода. Вывод MCP попадает в модель и часто в расшифровку чата, которую невозможно взять назад. Пароли, bearer-токены и JWT удаляются из каждой ошибки и ответа, прежде чем покинуть процесс.

Не допускает утечки учётных данных по сети. Обычный HTTP к удалённому хосту отклоняется при запуске; он разрешён только для localhost при локальной разработке.

Установка

Три способа запуска. Самостоятельный хостинг — это вариант по умолчанию и рекомендуемый — размещённый инстанс существует, чтобы вы могли попробовать его за две минуты, ничего не клонируя.

Если вы размещаете сервер самостоятельно и хотите использовать его в Claude web, запустите его с UMAMI_MCP_OAUTH=true за своим собственным доменом — тогда ничто ваше не коснётся чужой инфраструктуры.

1. Используйте размещённый инстанс (ничего устанавливать не нужно)

Добавьте пользовательский коннектор в Claude, указав:

https://umami-mcp.asif.dev/mcp

Вас попросят указать ваш собственный URL Umami и логин на экране согласия. См. Claude web, Cowork, and Claude Code on web о том, как обрабатываются учётные данные.

2. Из исходного кода

git clone https://github.com/Asif2BD/umami-mcp.git
cd umami-mcp
npm install && npm run build

Затем настройте учётные данные и зарегистрируйте его в вашем клиенте:

claude mcp add umami --scope user -- node "$PWD/dist/index.js"

Требуется Node 20 или новее.

3. Docker

git clone https://github.com/Asif2BD/umami-mcp.git
cd umami-mcp
cp .env.example .env    # then edit .env
docker compose up -d

npm: ещё не опубликован. Как только это произойдёт, npx -y @asif2bd/umami-mcp заменит шаг клонирования и сборки выше. А пока используйте исходники или Docker.

Учётные данные

У самостоятельно размещённого Umami нет API-ключей, поэтому учётные данные, которые хранит этот сервер, — это настоящий пароль от аккаунта. MCP-клиенты обычно ожидают, что он будет встроен в их JSON-конфиг — ~/.claude.json, mcp.json и тому подобное, — который широко доступен для чтения, попадает в issue и скриншоты, а некоторыми клиентами синхронизируется между машинами.

Поэтому этот сервер вместо этого читает учётные данные из файла, которым вы управляете. Создайте его один раз:

mkdir -p ~/.config/umami-mcp
cat > ~/.config/umami-mcp/env <<'EOF'
UMAMI_URL=https://analytics.example.com
UMAMI_USERNAME=mcp-bot
UMAMI_PASSWORD=your-password
UMAMI_MCP_MODE=read
EOF
chmod 600 ~/.config/umami-mcp/env

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

Порядок поиска — побеждает первый найденный файл, а настоящие переменные окружения всегда имеют приоритет над файлом, так что вы по-прежнему можете передавать настройки из конфига клиента, когда захотите:

1. $UMAMI_MCP_ENV_FILE, если задан

2. ~/.config/umami-mcp/env (или $XDG_CONFIG_HOME/umami-mcp/env)

3. ./.env в рабочем каталоге

Подключение клиента

Claude Code

С указанным выше файлом учётных данных регистрация вообще не содержит секретов:

claude mcp add umami --scope user -- node ~/umami-mcp/dist/index.js

Используйте абсолютный путь к вашему клону. Если ваш Node находится под nvm, укажите также полный путь к интерпретатору, поскольку MCP-клиенты не загружают ваш shell-профиль:

claude mcp add umami --scope user -- ~/.nvm/versions/node/v22.22.0/bin/node ~/umami-mcp/dist/index.js

Claude Desktop / Cursor / VS Code

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

Если вы предпочитаете хранить всё в одном месте, переменные окружения по-прежнему работают и имеют приоритет над файлом:

{
  "mcpServers": {
    "umami": {
      "command": "node",
      "args": ["/absolute/path/to/umami-mcp/dist/index.js"],
      "env": {
        "UMAMI_URL": "https://analytics.example.com",
        "UMAMI_USERNAME": "mcp-bot",
        "UMAMI_PASSWORD": "your-password"
      }
    }
  }
}

Проверьте, что работает

Попросите вашего клиента выполнить umami_whoami. Он сообщает инстанс, аккаунт и режим разрешений — самый быстрый способ подтвердить подключение и увидеть, что серверу разрешено делать:

{
  "instance": "https://analytics.example.com",
  "authenticatedAs": "mcp-bot",
  "role": "admin",
  "serverMode": "read",
  "destructiveOperations": "disabled"
}

Затем попробуйте: «Список моих веб-сайтов Umami» или «Какими были мои самые посещаемые страницы на прошлой неделе?»

Claude web, Cowork, and Claude Code on web

Эти клиенты не могут запускать локальный процесс, поэтому им нужен публичный HTTPS MCP-сервер — а их интерфейс коннектора принимает только OAuth, без поля для статического bearer-токена или пользовательского заголовка.

Хостинг очевидным способом — с одним встроенным набором учётных данных Umami и без аутентификации — превращает URL в открытый прокси к этому Umami. Поэтому этот сервер вместо этого использует OAuth и делает это, не превращаясь в хранилище учётных данных.

Используйте размещённый инстанс

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

https://umami-mcp.asif.dev/mcp

Claude регистрируется сам, отправляет вас на экран согласия и запрашивает ваш собственный URL Umami, имя пользователя и пароль. Ничто не передаётся другим пользователям хоста.

Разместите свой собственный

UMAMI_MCP_OAUTH=true
UMAMI_MCP_TRANSPORT=http
UMAMI_MCP_ISSUER=https://mcp.example.com      # public HTTPS URL of this server
UMAMI_MCP_TOKEN_KEY=<32 random bytes>          # keep stable; see below
UMAMI_MCP_TOKEN_TTL=2592000                    # 30 days

Сгенерируйте ключ один раз и сохраните его:

node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"

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

Как обрабатываются учётные данные

Экран согласия проверяет учётные данные на том инстансе Umami, который указал пользователь, а затем запечатывает их в токен доступа с помощью AES-256-GCM. Сервер не хранит ни таблицы сессий, ни учётных данных: каждый запрос расшифровывает токен, создаёт MCP-сервер в рамках этого одного пользователя, обслуживает вызов и отбрасывает его.

Честный компромисс: тот, кто владеет UMAMI_MCP_TOKEN_KEY, может расшифровать любой захваченный токен. Относитесь к нему как к самому чувствительному значению в развёртывании. Его ротация аннулирует каждый выпущенный токен — это и есть предусмотренный контроль радиуса поражения.

Разрушительные инструменты никогда не предоставляются через OAuth, независимо от того, какое разрешение выберет пользователь. Их защита с текстовым подтверждением предполагает локального оператора, который видит, что собирается удалить, а удалённому вызывающему это показать нельзя.

Запуск в качестве обычного HTTP-сервиса

Установите UMAMI_MCP_TRANSPORT=http без UMAMI_MCP_OAUTH для однотенантной конечной точки /mcp, плюс /health.

В этом режиме у сервера нет собственной аутентификации. Любой, кто может дотянуться до порта, может использовать ваши учётные данные Umami. Держите его на loopback и туннелируйте к нему:

ssh -N -L 3334:127.0.0.1:3334 you@your-server
claude mcp add --transport http umami http://127.0.0.1:3334/mcp

Сервер предупреждает при запуске, если он привязан к чему-либо, кроме loopback.

Инструменты

Диапазоны времени

Каждый аналитический инструмент принимает сокращённую форму period — 24h, 7d, 30d, 12m, today, yesterday — вместо миллисекунд с начала эпохи Unix. Модели надёжно справляются с запросом «последние 30 дней», но ненадёжны в арифметике меток времени, а ошибочно вычисленная эпоха вернёт данные за неверный период без ошибки. Явные startAt/endAt в миллисекундах с начала эпохи Unix по-прежнему работают и имеют приоритет.

Конфигурация

Все параметры перечислены в .env.example. Основные:

Рекомендуемая настройка

Создайте для MCP-сервера отдельную учётную запись Umami, а не используйте повторно свой административный логин, и предоставьте ей только те сайты, которые нужны. Тогда даже при раскрытии учётных данных зона поражения ограничится одним бот-аккаунтом, который можно удалить, — а не вашим администратором.

Совместимость

Проверено на Umami 3.3.1 (self-hosted, PostgreSQL). Umami Cloud работает через UMAMI_API_KEY. Umami v2 не поддерживается: переименованные выше типы метрик означают, что для v2 и v3 нужны разные клиенты, а этот ориентирован на v3.

Разработка

npm install
npm run build
npm test          # unit tests, no network required

test/e2e.mjs и test/write-e2e.mjs управляют собранным сервером через реальный MCP-клиент, подключаясь к живой инстанции. Write-тест создаёт временный сайт на домене .invalid, а затем удаляет его; направляйте его на непродакшн-инстанцию.

Вклад в проект

Приветствуются issues и pull request'ы. Umami v3 предоставляет около 127 API-маршрутов, и этот сервер покрывает самые полезные из них — воспроизведение сеансов, тепловые карты, пиксели, отслеживание ссылок, доски и сегменты пока не реализованы. Добавляя инструменты, честно указывайте уровень и флаг destructive, поскольку на них строится вся модель безопасности.

Если команда Umami захочет перенять, форкнуть или включить это в свой проект, пожалуйста, откройте issue — именно для этого он и создавался.

Лицензия

MIT © M Asif Rahman