caldav-mcp

caldav-mcp

<div align="center">

🗓️ A CalDAV Model Context Protocol (MCP) server to expose calendar operations as tools for AI assistants.

     

</div>

✨ Features

• Connect to CalDAV servers
• List calendars
• List calendar events within a specific timeframe
• Create calendar events
• Update calendar events
• Delete calendar events by UID

Setup

{
  "mcpServers": {
    ...,
    "calendar": {
      "command": "npx",
      "args": [
        "caldav-mcp"
      ],
      "env": {
        "CALDAV_BASE_URL": "<CalDAV server URL>",
        "CALDAV_USERNAME": "<CalDAV username>",
        "CALDAV_PASSWORD": "<CalDAV password>"
      }
    }
  }
}

Development

Quick Start

Run the MCP server in development mode with auto-reload: ``bash npm run dev ``

This will run the TypeScript code directly with watch mode and automatically load environment variables from .env.

Manual Build

Alternatively, you can compile TypeScript to JavaScript and run it:

1. Compile:

npx tsc

1. Run:

node dist/index.js

Available Tools

<!-- TOOLS:START - generated by scripts/gen-tool-docs.ts -->

list-calendars

List all calendars returning both name and URL

Parameters: none

Returns:

• List of all available calendars

list-events

List all events between start and end date in the calendar specified by its URL

Parameters:

• start: string — Start date (ISO 8601)
• end: string — End date (ISO 8601)
• calendarUrl: string

Returns:

• A list of events that fall within the given timeframe, each containing uid, summary, start, end, and optionally description and location

create-event

Creates an event in the calendar specified by its URL. For all-day events, set wholeDay to true. For a single-day all-day event, use start and end datetimes on the same calendar date; they do not need to be identical timestamps.

Parameters:

• summary: string
• start: string — Start datetime (ISO 8601)
• end: string — End datetime (ISO 8601)
• wholeDay: boolean (optional) — Create as a whole-day event
• calendarUrl: string
• description: string (optional)
• location: string (optional)
• recurrenceRule: object (optional)
• freq: enum (DAILY | WEEKLY | MONTHLY | YEARLY) (optional)
• interval: number (optional)
• count: number (optional)
• until: string (optional)
• byday: array of string (optional)
• bymonthday: array of number (optional)
• bymonth: array of number (optional)

Returns:

• The unique ID of the created event

update-event

Updates an existing event in the calendar specified by its URL. Only provided fields are changed. For a one-day full-day event, set wholeDay to true and set start and end to the same calendar day.

Parameters:

• uid: string — Unique identifier of the event to update (obtained from list-events)
• calendarUrl: string
• summary: string (optional)
• start: string (optional)
• end: string (optional)
• wholeDay: boolean (optional) — Update whether this is a whole-day event
• description: string (optional)
• location: string (optional)
• recurrenceRule: object (optional)
• freq: enum (DAILY | WEEKLY | MONTHLY | YEARLY) (optional)
• interval: number (optional)
• count: number (optional)
• until: string (optional)
• byday: array of string (optional)
• bymonthday: array of number (optional)
• bymonth: array of number (optional)

Returns:

• The unique ID of the updated event

delete-event

Deletes an event in the calendar specified by its URL

Parameters:

• uid: string — Unique identifier of the event to delete (obtained from list-events)
• calendarUrl: string

Returns:

• Confirmation message when the event is successfully deleted

list-todos

List tasks (VTODOs) in the calendar specified by its URL. By default returns only open tasks (NEEDS-ACTION and IN-PROCESS), sorted by manual order then due date. Use status to include completed (COMPLETED) or all (ALL) tasks, and limit/offset to page through long lists.

Parameters:

• calendarUrl: string
• status: enum (OPEN | ALL | NEEDS-ACTION | COMPLETED | IN-PROCESS | CANCELLED) (optional) — Filter by status. OPEN (default) = NEEDS-ACTION + IN-PROCESS; ALL = everything; or an exact status (NEEDS-ACTION, COMPLETED, IN-PROCESS, CANCELLED).
• due_before: string (optional) — Only tasks with a due date at or before this (ISO 8601). Undated tasks are excluded when a due window is set.
• due_after: string (optional) — Only tasks with a due date at or after this (ISO 8601). Undated tasks are excluded when a due window is set.
• limit: number (optional) — Max tasks to return (default 50, max 500)
• offset: number (optional) — Tasks to skip (default 0)

Returns:

• An object { todos, total, limit, offset } where total is the count before pagination. Each todo has uid, summary, status, and optionally due, start, completed, description, location.

create-todo

Creates a task (VTODO) in the calendar specified by its URL. Only summary is required; a task may have no dates. Use due for a deadline and start for when work should begin.

Parameters:

• summary: string
• calendarUrl: string
• due: string (optional) — Due datetime (ISO 8601)
• start: string (optional) — Start datetime (ISO 8601)
• description: string (optional)
• location: string (optional)
• status: enum (NEEDS-ACTION | COMPLETED | IN-PROCESS | CANCELLED) (optional) — Defaults to NEEDS-ACTION when omitted

Returns:

• The unique ID of the created todo

update-todo

Updates an existing task (VTODO) in the calendar specified by its URL. Only provided fields are changed. To mark a task done, prefer the complete-todo tool.

Parameters:

• uid: string — Unique identifier of the todo to update (from list-todos)
• calendarUrl: string
• summary: string (optional)
• due: string (optional)
• start: string (optional)
• description: string (optional)
• location: string (optional)
• status: enum (NEEDS-ACTION | COMPLETED | IN-PROCESS | CANCELLED) (optional)

Returns:

• The unique ID of the updated todo

complete-todo

Marks a task (VTODO) as done. Sets its status to COMPLETED and records the completion time.

Parameters:

• uid: string — Unique identifier of the todo to complete (from list-todos)
• calendarUrl: string

Returns:

• The unique ID of the completed todo

delete-todo

Deletes a task (VTODO) in the calendar specified by its URL

Parameters:

• uid: string — Unique identifier of the todo to delete (from list-todos)
• calendarUrl: string

Returns:

• Confirmation message when the todo is successfully deleted

<!-- TOOLS:END -->

License

MIT