mcpField
U
umami

umami

github.com/martinhjartmyrData & databases039 installsUpdated 33w ago
Repository

About umami

umami is a skill for retrieving traffic summaries and analytics from an Umami instance, for users who need to review website activity. It summarizes current and previous-period metrics and can also fetch active visitor counts alone.

Key features

  1. 01Fetch website traffic summaries
  2. 02Compare current and previous-period metrics
  3. 03Retrieve current active visitor counts
  4. 04Format analytics as tables

Use cases

  1. 01Prepare a daily website traffic report
  2. 02Check the current number of active visitors

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/martinhjartmyr/skills --skill umami

After installing, type/umamiin Claude Code to confirm it loaded.

Bundled filesreferences/api.mdscripts/umami-summary.sh

Details

From the project README

Umami Analytics

Fetch traffic summaries and analytics data from an Umami instance.

Configuration

Set these environment variables before running:

VariableRequiredDescription
UMAMI_API_URLYesBase URL of your Umami instance (e.g. https://cloud.umami.is)
UMAMI_API_KEYOne of theseAPI key for Umami Cloud. Used as Bearer token directly.
UMAMI_USERNAMEOne of theseUsername for self-hosted login via /api/auth/login.
UMAMI_PASSWORDWith usernamePassword for self-hosted login.

If UMAMI_API_KEY is set, it takes precedence over username/password.

Workflow: Daily Traffic Summary

  1. Run the script: 
    bash ~/Projects/skills/umami/scripts/umami-summary.sh
  2. Parse the JSON output.
  3. Format as a markdown table:
WebsiteDomainPageviewsVisitorsVisitsBouncesAvg TimeActive
My Blogblog.example.com1,234 (980)567 (510)890 (801)123 (110)45s (38s)3
Totals1,234 (980)567 (510)890 (801)123 (110)45s (38s)3
  • Show previous period values in parentheses after each metric (e.g. "1,234 (980)" means 1,234 current, 980 previous).
  • Format numbers with commas for readability.
  • Convert totaltime to human-readable duration (e.g. "1m 23s").
  • Calculate average time as totaltime / visits for each site, using prev_totaltime / prev_visits for the previous period.
  • Bold the totals row.

Workflow: Active Users Only

For "who is on my site right now?" queries, use the lightweight flag:

bash ~/Projects/skills/umami/scripts/umami-summary.sh --active-only

This skips the stats API calls and only fetches current active visitor counts. Format as a simpler table:

WebsiteDomainActive
My Blogblog.example.com3

Error Handling

The script exits non-zero and writes JSON to stderr on failure:

  • Missing env vars: {"error": "UMAMI_API_URL is not set"}
  • Auth failure: {"error": "Authentication failed (HTTP 401)"}
  • Unreachable server: {"error": "Could not connect to https://..."}

Report these errors clearly to the user with the specific message. Suggest checking their environment variables.

API Reference

For queries beyond the daily summary (time series, metrics breakdowns, custom date ranges), see references/api.md.

Comments

Markdown supported