Umami Analytics Skill

Cursor Agent Skill for fetching and analyzing website traffic from a self-hosted Umami instance.

Setup

1. Install dependencies:

npm install

2. Copy credentials:

cp .env.example .env

3. Fill in .env:

Variable	Description
UMAMI_API_CLIENT_ENDPOINT	Your Umami API base URL, e.g. https://analytics.example.com/api
UMAMI_USERNAME	Umami login username
UMAMI_PASSWORD	Umami login password
UMAMI_API_CLIENT_SECRET	Optional; only for token-based auth, not needed with login/password
UMAMI_WEBSITE_ID	Optional default website UUID
UMAMI_TIMEZONE	Optional, default Asia/Shanghai

4. Link the skill in Cursor (already included at .cursor/skills/umami/SKILL.md when using this repo as your workspace).

CLI Usage

# List accessible websites
node scripts/umami-cli.mjs websites

# Summary stats for the last 7 days
node scripts/umami-cli.mjs stats --period 7d

# Pageview trend (daily buckets)
node scripts/umami-cli.mjs pageviews --period 30d --unit day

# Top pages
node scripts/umami-cli.mjs metrics --type path --limit 10

# Real-time active visitors
node scripts/umami-cli.mjs active

# Custom event stats
node scripts/umami-cli.mjs events --period 7d

# Available data date range
node scripts/umami-cli.mjs daterange

All commands output JSON to stdout. Errors go to stderr.

Common flags:

• --website <id> — override UMAMI_WEBSITE_ID
• --period 24h|7d|30d|90d — relative time range
• --start YYYY-MM-DD --end YYYY-MM-DD — absolute range
• --timezone Asia/Shanghai — timezone for time-series endpoints

Using with Cursor

Ask the agent questions like:

• "分析我网站最近一周的流量"
• "哪些页面访问量最高？"
• "流量主要来自哪些渠道？"

The agent reads SKILL.md and runs the CLI to fetch real data before writing a report.

Files

File	Purpose
SKILL.md	Agent workflow and report template
reference.md	API parameters and metric types
examples.md	Question → CLI command mapping
scripts/umami-cli.mjs	Data fetching CLI