CalDAV API returns UTC timestamps without user timezone metadata — silent footgun for programmatic consumers (AI agents, CLI tools, automations)

Describe the bug

The CalDAV API returns all event timestamps in UTC (e.g., 2026-04-22T00:00:00+00:00). This is correct per RFC5545. However, the API provides no user timezone metadata in responses — no timezone identifier, no UTC offset, no hint about what timezone the user actually lives in.

For browser-based calendar clients, this is fine: JavaScript resolves the timezone automatically. But for programmatic consumers — AI agents, CLI tools, automation pipelines, MCP servers — there is no browser. The consumer receives a UTC timestamp and must independently determine the user's timezone to display, compare, or reason about event times correctly.

Why this matters now

AI agents interacting with calendars are becoming common (via MCP servers, LangChain tools, custom integrations). These agents routinely:

• Compare calendar events for scheduling conflicts
• Present event times to users in natural language
• Create events on behalf of users

Without timezone context, an agent sees 2026-04-22T00:00:00Z and must guess whether that means April 21 at 7pm CDT, April 22 at 8am JST, or something else entirely. Getting this wrong produces embarrassing real-world consequences — missed appointments, false conflict reports, events created on the wrong day.

I personally experienced this: an AI agent compared a UTC midnight timestamp against another event and reported a scheduling conflict that didn't exist, because it calculated the offset incorrectly and placed the event on the wrong local date.

Existing related issues

• #4156 — Incorrect timezone display in web UI (browser-focused)
• #5734 — Timezone disparity between web UI and Thunderbird/Merkuro (client display)
• #1012 — UTC events edited in UTC instead of local time (UI editing)

These all address display problems. This issue addresses the API/data problem for non-browser consumers.

Proposed solutions (any one would help)

1. Include user timezone in CalDAV API responses — Add a X-NC-USER-TZ: America/Chicago header or equivalent metadata to calendar queries, so programmatic consumers know the user's timezone without guessing.

2. Add optional timezone query parameter — Allow ?tz=America/Chicago or ?local=true to return timestamps pre-converted to the user's local timezone, similar to how the web UI resolves them.

3. Document the footgun — At minimum, add prominent documentation in the CalDAV API docs warning that all timestamps are UTC and consumers must independently resolve the user's timezone.

Calendar app version

Current (as of April 2026)

CalDAV clients used

AI agent via MCP server (nextcloud-mcp), CLI tools (openclaw-nextcloud), Python scripts using caldav library

Browser

N/A — this is not a browser issue

Operating system

N/A

Additional context

This is a forward-looking concern. As AI agents become ubiquitous calendar consumers, the silent UTC-without-timezone pattern will cause increasing real-world problems. A small API enhancement now prevents a class of bugs that are easy to make and hard to detect.

The root issue isn't that CalDAV returns UTC — that's correct. It's that there's no standard mechanism for a programmatic consumer to discover the user's intended timezone without either (a) having a browser, (b) hardcoding it in config, or (c) querying a separate settings endpoint that may not exist.

Start by locating the CalDAV API entry points and the existing API documentation; no specific files or tests are named in the issue. First determine which proposed timezone contract the maintainers want, then define completion around that contract and add the corresponding API coverage or documentation.