7.2 KiB
7.2 KiB
name, description
| name | description |
|---|---|
| umami | Self-hosted Umami Analytics integration with username/password authentication. Use to create websites, get tracking codes, and fetch analytics data. |
📊 Umami Analytics Skill
Skill Name: umami
Category: quick
Load Skills: []
🚀 Purpose
Integrate with self-hosted Umami Analytics using username/password authentication (like Easypanel):
- ✅ Auto-login - Get bearer token from credentials
- ✅ Create websites - Auto-create Umami website for new projects
- ✅ Get tracking code - Retrieve script URL for website integration
- ✅ Fetch analytics - Get pageviews, visitors, bounce rate
- ✅ List websites - Get all websites in Umami instance
Use Cases:
- Auto-create Umami website when generating new website
- Add tracking code to Astro website automatically
- Fetch analytics data for SEO analysis
- Manage multiple Umami websites
📋 Pre-Flight Questions
MUST ask before using:
-
Umami Instance URL:
- What's your Umami URL? (e.g., https://analytics.moreminimore.com)
-
Authentication:
- Username/email
- Password
-
For Website Creation:
- Website name
- Website domain
-
For Existing Website:
- Website name or domain (to find in Umami)
🔄 Workflows
Workflow 1: Auto-Login (First Step for All Operations)
Input: Umami URL, username, password
Process:
1. POST /api/auth/login
2. Get bearer token
3. Save token for subsequent requests
Output: Bearer token + user info
Workflow 2: Create Umami Website
Input: Website name, domain
Process:
1. Login (get token)
2. POST /api/websites
3. Get website ID
Output: Website ID, name, domain, tracking URL
Workflow 3: Get Tracking Code
Input: Website ID or domain
Process:
1. Get website ID
2. Generate tracking script URL
Output: Script tag or URL
Workflow 4: Add Tracking to Website
Input: Website repo path, Umami website ID
Process:
1. Get tracking code
2. Find Astro root layout
3. Add script to <head>
4. Save file
Output: Updated layout file
Workflow 5: Fetch Analytics
Input: Website ID, date range
Process:
1. GET /api/websites/:id/stats
2. Parse response
Output: Pageviews, visitors, bounce rate, etc.
🔧 Technical Implementation
Authentication:
POST {umami_url}/api/auth/login
Content-Type: application/json
{
"username": "your-username",
"password": "your-password"
}
Response:
{
"token": "eyJhbGciOiJIUzI1NiIs...",
"user": {
"id": "uuid",
"username": "admin",
"isAdmin": true
}
}
Create Website:
POST {umami_url}/api/websites
Authorization: Bearer {token}
Content-Type: application/json
{
"name": "My Website",
"domain": "example.com"
}
Response:
{
"id": "website-uuid",
"name": "My Website",
"domain": "example.com",
"createdAt": "2026-03-08T..."
}
Get Tracking Code:
// Script URL format
<script defer src="{umami_url}/script.js" data-website-id="{website_id}"></script>
// Or for Fathom-style (if enabled)
<script defer src="{umami_url}/script.js" data-site-id="{website_id}"></script>
Get Stats:
GET {umami_url}/api/websites/{website_id}/stats
?startAt={timestamp}
&endAt={timestamp}
Authorization: Bearer {token}
Response:
{
"pageviews": 1234,
"uniques": 567,
"bounces": 89,
"totaltime": 12345
}
📁 Commands
Create Umami Website:
python3 skills/umami/scripts/umami_client.py \
--action create-website \
--umami-url "https://analytics.moreminimore.com" \
--username "admin" \
--password "your-password" \
--website-name "My Website" \
--website-domain "example.com"
Get Tracking Code:
python3 skills/umami/scripts/umami_client.py \
--action get-tracking \
--umami-url "https://analytics.moreminimore.com" \
--username "admin" \
--password "your-password" \
--website-id "website-uuid"
Add Tracking to Website:
python3 skills/umami/scripts/umami_client.py \
--action add-tracking \
--umami-url "https://analytics.moreminimore.com" \
--username "admin" \
--password "your-password" \
--website-name "My Website" \
--website-repo "/path/to/astro-website"
Fetch Analytics:
python3 skills/umami/scripts/umami_client.py \
--action get-stats \
--umami-url "https://analytics.moreminimore.com" \
--username "admin" \
--password "your-password" \
--website-id "website-uuid" \
--days 30
⚙️ Environment Variables
Updated for username/password auth:
# Umami Analytics (Self-Hosted)
UMAMI_URL=https://analytics.yoursite.com
UMAMI_USERNAME=admin
UMAMI_PASSWORD=your-password
Note: Changed from API key to username/password like Easypanel
📊 Output Examples
Create Website Output:
{
"success": true,
"website_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "My Website",
"domain": "example.com",
"tracking_url": "https://analytics.moreminimore.com/script.js",
"tracking_script": "<script defer src=\"https://analytics.moreminimore.com/script.js\" data-website-id=\"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"></script>",
"created_at": "2026-03-08T16:00:00.000Z"
}
Stats Output:
{
"success": true,
"website_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"period": "last_30_days",
"stats": {
"pageviews": 12500,
"uniques": 8900,
"bounces": 1200,
"totaltime": 245000,
"avg_session_duration": 27.5,
"bounce_rate": 13.5
}
}
🔄 Integration with Other Skills
website-creator Integration:
# After creating Astro website
umami_result = create_umami_website(
umami_url, username, password,
website_name, website_domain
)
if umami_result['success']:
# Add tracking to Astro layout
add_tracking_to_astro(
website_repo,
umami_result['tracking_script']
)
seo-data Integration:
# Replace umami_connector.py stub
from umami import UmamiClient
umami = UmamiClient(umami_url, username, password)
stats = umami.get_page_data(website_id, days=30)
✅ Success Criteria
- Can login with username/password
- Can create new Umami website
- Can get tracking code
- Can add tracking to Astro website
- Can fetch analytics data
- Token cached for subsequent requests
⚠️ Important Notes
- Self-Hosted Only: This skill is for self-hosted Umami instances
- Username/Password: Uses login API, not API keys (Umami Cloud uses API keys)
- Token Caching: Bearer token should be cached to avoid repeated logins
- Website Domain: Must be full domain (https://example.com)
- Script URL: Depends on Umami instance URL
📖 API Reference
- Login: POST /api/auth/login
- Create Website: POST /api/websites
- Get Website: GET /api/websites/:id
- Get Stats: GET /api/websites/:id/stats
- List Websites: GET /api/websites
Full docs: https://umami.is/docs/api
Use this skill when you need to integrate with self-hosted Umami Analytics using username/password authentication.