caldav-mcp

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

✨ 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:

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

2. Run:

node dist/index.js

Available Tools

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

Parameters:

• summary: string
• start: string — Start datetime (ISO 8601)
• end: string — End datetime (ISO 8601)
• 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.

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)
• 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

License

MIT