Add MCP tool to list calendar events by date range

[wollir72]

Feature Request: Add MCP tool to list calendar events by date range

Summary

The Nextcloud Context Agent currently exposes several calendar-related MCP tools, including:

• list_calendars
• schedule_event
• list_tasks
• find_free_time_slot_in_calendar

However, there is currently no MCP tool that allows a client to directly list existing calendar events (VEVENT) within a given time range.

This makes common queries such as:

• "Show me all appointments this month"
• "What events do I have during the next four weeks?"
• "Show me my appointments for next week"

difficult or impossible to answer reliably through MCP.

The global event search can accept since and until filters, but it behaves like a search facility rather than a calendar event listing API and does not provide a reliable replacement for querying VEVENTs by date range.

Proposed MCP tool

Please add a dedicated read-only MCP tool such as:

list_events(
    start,
    end,
    calendar_name=None
)

or:

list_calendar_events(
    start,
    end,
    calendar_name=None
)

Parameters

• start: Start of the requested time range
• end: End of the requested time range
• calendar_name: Optional calendar name; if omitted, query all calendars accessible to the user

ISO 8601 timestamps would be preferable, for example:

2026-08-01T00:00:00+02:00
2026-09-01T00:00:00+02:00

Expected result

The tool should return structured event information, for example:

[
  {
    "calendar": "Personal",
    "uid": "example-event-uid",
    "summary": "Dentist",
    "start": "2026-08-12T14:00:00+02:00",
    "end": "2026-08-12T15:00:00+02:00",
    "all_day": false,
    "location": "Nuremberg",
    "description": "",
    "status": "CONFIRMED"
  }
]

Important requirements

The implementation should support:

• Events from all calendars or a selected calendar
• Date/time range filtering
• Timed events
• All-day events
• Recurring events
• Recurrence exceptions and modified occurrences
• Correct timezone handling
• Read-only operation

Recurring events are especially important. When querying a time range, the MCP client should receive the actual event occurrences within that range rather than only the original VEVENT containing an RRULE.

Use case

I am using the official Nextcloud Context Agent 2.7.0 with Nextcloud 34 and ChatGPT through MCP.

ChatGPT can currently discover my calendars and create events, but it cannot reliably answer basic calendar questions such as:

"Show me all events this month."

A dedicated list_events tool would make calendar access substantially more useful for MCP clients and AI assistants while keeping the operation simple and read-only.

The existing list_tasks tool already provides similar functionality for VTODO items, so an equivalent tool for VEVENTs would make the calendar API much more complete.