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

<!-- TOOLS:END -->

License

MIT