v3.4.0

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](https://github.com/umami-software/umami/blob/v3.4.0/packages/mcp/README.md) 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](https://github.com/umami-software/umami/blob/v3.4.0/docs/report-api-migration.md) 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**: https://github.com/umami-software/umami/compare/v3.3.1...v3.4.0