umami-software/umami v3.4.0

on GitHub

Umami v3.4.0 is here with new Annotations, MCP support, API key management, a typed API client, session property segments, and security, analytics, and UI improvements.

New features

Annotations

Add dated notes to your website charts to keep launches, campaigns, and other important events alongside your analytics.

• Chart markers for website annotations
• Create, edit, and delete annotations
• All-day and time-specific notes
• Annotation management and date picker improvements

Model Context Protocol (MCP)

Connect MCP-compatible assistants to Umami to explore your analytics with read-only tools.

• Tools for traffic, events, sessions, funnels, goals, journeys, retention, attribution, revenue, performance, segments, and annotations
• Remote HTTP endpoint and local stdio support through @umami/mcp
• API key authentication with existing user and team permissions
• Self-hosted endpoint disabled by default; set MCP_ENABLED=1 to enable /mcp

See the MCP setup guide for configuration and examples.

API keys and typed API client

• Create and revoke account API keys under Settings → API keys
• New @umami/api-client TypeScript package generated from Umami's OpenAPI contracts
• Typed request parameters and responses, structured errors, and ESM/CommonJS support
• Generated OpenAPI documentation with endpoint and field descriptions

Analytics APIs

• Website-scoped GET endpoints for analytics queries
• Dedicated saved funnel and goal resources and stats endpoints
• Separate performance stats, chart, and metrics datasets
• Dedicated UTM metrics endpoint
• Legacy report APIs preserved through compatibility handlers

See the report API migration guide for endpoint mappings and compatibility details.

Segments and tracking

• Save session property filters in segments and combine them with active filters. #4507
• Set a visitor identity through the tracker data-distinct-id attribute. #4421
• Added New Taiwan Dollar (TWD) and Icelandic Króna (ISK) revenue currencies. #4444 #4516
• Added Georgian and Azerbaijani translations. #4495 #4520

Security

• Reject partial 2FA tokens for authenticated API access
• Bind authenticated sessions to password fingerprints
• Exclude deleted teams from access checks and invalidate their join codes
• Prevent website reassignment when updating reports
• Added Gitleaks secret scanning and refreshed security dependency overrides

Migrations

This release includes schema migrations for annotations and API keys:

• prisma/migrations/25_add_annotation
• prisma/migrations/26_add_api_key

Migrations run automatically during the build process. Existing saved report definitions and IDs are retained by the analytics API changes.

Fixes

• PostgreSQL and ClickHouse timezone inconsistencies. #4541 #3810
• Identified visitors sharing an IP address and user agent now receive separate sessions by distinct ID
• PostgreSQL session activity queries use correlated EXISTS to improve query behavior. #4528
• Removed unnecessary sorting from PostgreSQL visitor count queries. #4523
• API client path parameter handling
• Commas in regular-expression filter values are preserved. #4496
• Filter values stay in sync when operators change
• Custom page selector values. #4490
• Wildcard controls in goal and funnel forms
• Creating a board without a description. #4469
• Board handling when a referenced website has been deleted
• Pasting one-time passwords on mobile. #4465
• Fullscreen date filter dropdown on mobile
• Manage teams navigation respects the configured base path. #4502
• Hidden sidebar scrollbar when collapsed. #4472
• Full path metric label tooltips. #4533
• Website selector behavior, event detail wrapping, and chart tooltip styling

Updates

• Next.js 16.3.4
• Prisma 7.10.0
• React 19.3.0
• React Zen component library upgrades and shared theme tokens
• Refined team navigation and top navigation selectors
• API integration coverage for PostgreSQL and ClickHouse
• OpenAPI and generated client validation in CI
• Runtime, frontend, build tooling, and security dependency updates

Thanks

@Alphapin @GroophyLifefor @JoeJoeflyn @MontejoJorge @bm1016bm-svg @brantsrasmus @dongwonmoon @flamelin @franciscao633 @jamalkamaladdin @justadityaraj @luca-seemann @lukkshh @nicolas2601

Full Changelog: v3.3.1...v3.4.0