umami-compass
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| UMAMI_URL | No | Self-hosted Umami instance origin (e.g., https://analytics.example.com); /api is appended. | |
| UMAMI_API_KEY | No | Umami Cloud API key (x-umami-api-key). | |
| UMAMI_API_URL | No | Exact API root URL for self-hosted Umami (alternative to UMAMI_URL). | |
| UMAMI_PASSWORD | No | Password for self-hosted Umami login (used with UMAMI_USERNAME). | |
| UMAMI_TOOLSETS | No | Comma-separated toolsets or 'all'. Defaults to 'core'. | |
| UMAMI_USERNAME | No | Username for self-hosted Umami login (used with UMAMI_PASSWORD). | |
| UMAMI_WEBSITE_IDS | No | Comma-separated website UUID allowlist. | |
| UMAMI_ACCESS_TOKEN | No | Existing Bearer token for self-hosted Umami. | |
| UMAMI_MAX_RANGE_DAYS | No | Max analytics range in days (1-3650). Defaults to 366. | |
| UMAMI_MAX_RESPONSE_BYTES | No | Max decoded upstream JSON body bytes (102400-52428800). Defaults to 10485760. | |
| UMAMI_REQUEST_TIMEOUT_MS | No | Per-request timeout in ms (1000-120000). Defaults to 30000. | |
| UMAMI_ALLOW_INSECURE_HTTP | No | Allow non-loopback HTTP connections. Defaults to 'false'. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Secure, read-only Umami Analytics access. Start with resolve_website when the insights toolset is enabled, otherwise use list_websites. Use bounded time ranges and prefer insight workflows for traffic or performance portfolios, traffic-change, release-impact, and tracking-health decisions. Treat performanceEventCount as an all-performance-event count, not a metric-specific sample count; honor filterScope and scope_mismatch. Performance, saved reports, session, revenue, heatmap and replay data may require separate Umami permissions. Minimize sensitive data entering model context. No tool in this release changes Umami state.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
| prompts | {
"listChanged": true
} |
| resources | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| get_server_infoA | Get the local package version, enabled toolsets, safety limits, and supported analysis capabilities without exposing credentials. |
| list_websitesA | List websites visible directly or through any team membership of the configured Umami identity. If UMAMI_WEBSITE_IDS is set, returns only that exact allowlist. |
| get_websiteC | Get metadata for one website. |
| get_website_statsB | Get visits, visitors, pageviews, bounces, visit duration and Umami's comparison values for a time range. |
| get_pageviewsC | Get Umami 3.2 pageview and session time series. Both arrays are preserved in the response. |
| get_metricsB | Get a ranked aggregate Umami metric breakdown such as paths, referrers, countries, devices, events, channels or URLs. Visitor identifiers are excluded from the core toolset. |
| get_active_visitorsB | Get the current number of active visitors for a website. |
| get_website_date_rangeA | Get the earliest and latest analytics timestamps available for a website. |
| resolve_websiteA | Resolve a website UUID from a UUID, domain, URL, or website name. Ambiguous matches return bounded candidates instead of guessing. |
| get_portfolio_overviewB | Summarize bounded aggregate traffic across visible websites, including period changes, growth and decline leaders, stale tracking, failures, and suspicious jumps. |
| analyze_performance_portfolioB | Compare Core Web Vitals across a bounded website portfolio with compact-by-default output, metric-specific drill-down selection, confidence, event/pageview ratios, and precise section truncation metadata. |
| explain_traffic_changeA | Compare traffic with a previous, year-over-year, or custom period and rank observed changes across pages, referrers, countries, devices, channels, and events. Results describe association, not causation. |
| compare_traffic_seriesB | Return aligned current and comparison traffic buckets to locate the exact day or hour when traffic changed. |
| analyze_release_impactA | Compare equal pre- and post-release windows across traffic breakdowns and Core Web Vitals. Returns a compact executive summary by default; request full detail for drill-down evidence. Recent releases use a partial post window and an equally shortened pre window. |
| tracking_health_checkB | Audit visible websites for stale or missing traffic, traffic drops, domain mismatches, referral-spam patterns, custom-event availability, recorder configuration, and section permission failures. Disabled optional features are warnings only when marked as expected. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| analytics_report | A safe workflow for producing an evidence-based analytics report. |
| weekly_portfolio_briefing | Produce a bounded weekly briefing across visible websites with leaders, declines, anomalies, stale tracking, and next actions. |
| investigate_traffic_change | Explain a website traffic increase or decrease with bounded supporting evidence. |
| release_impact_report | Assess traffic and Web Vitals before and after a deployment. |
| tracking_health_audit | Check freshness, domains, events, recorder configuration, and permissions across websites. |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| websites | Websites visible under the configured identity and optional allowlist. |
| capabilities | Sanitized local capability, scope, and safety-limit information without credentials. |
TDQS
Scored across 15 tools
Most tools target clearly distinct slices: site resolution/listing/metadata, aggregate stats, time series, ranked breakdowns, realtime, and date range are all separable. The analysis layer has mild overlap — explain_traffic_change, compare_traffic_series, and analyze_release_impact all perform period comparisons, and an agent could hesitate between them, though descriptions clarify (ranking vs. aligned buckets vs. release windows with CWV).
Strong verb_noun snake_case pattern throughout (get_website_stats, list_websites, resolve_website, analyze_release_impact, compare_traffic_series). The only deviation is tracking_health_check, which is noun-first with no leading verb, but it remains readable and predictable in intent.
15 tools sits at the top of the comfortable range for an analytics server and each has a defensible role. The higher-order analysis tools (release impact, traffic change, series comparison) do compose functionality already exposed by the base stats/metrics tools, which makes the set slightly heavier than strictly necessary.
Covers the read-only analytics lifecycle well: discovery (list/get/resolve), quantitative stats, series, dimension breakdowns, realtime, portfolio rollups, CWV, and health auditing, with sensible safety bounds and explicit truncation metadata. Gaps exist around session/event-level drill-down, saved reports or export, and any write operations (site creation, share links), but these are outside the apparent analysis-focused scope.