Connect to CalDAV for Calendar Management

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. 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

scripts/gen-tool-docs.ts

#!/usr/bin/env tsx
import { readFileSync, writeFileSync } from "node:fs";
import { dirname, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import { z } from "zod";

import { completeTodoDefinition } from "../src/tools/complete-todo.js";
import { createEventDefinition } from "../src/tools/create-event.js";
import { createTodoDefinition } from "../src/tools/create-todo.js";
import { deleteEventDefinition } from "../src/tools/delete-event.js";
import { deleteTodoDefinition } from "../src/tools/delete-todo.js";
import { listCalendarsDefinition } from "../src/tools/list-calendars.js";
import { listEventsDefinition } from "../src/tools/list-events.js";
import { listTodosDefinition } from "../src/tools/list-todos.js";
import { updateEventDefinition } from "../src/tools/update-event.js";
import { updateTodoDefinition } from "../src/tools/update-todo.js";

type ToolDefinition = {
	name: string;
	description: string;
	inputSchema: Record<string, z.ZodTypeAny>;
	returns?: string;
};

// Render order is significant: this is the order tools appear in the README.
const TOOLS: ToolDefinition[] = [
	listCalendarsDefinition,
	listEventsDefinition,
	createEventDefinition,
	updateEventDefinition,
	deleteEventDefinition,
	listTodosDefinition,
	createTodoDefinition,
	updateTodoDefinition,
	completeTodoDefinition,
	deleteTodoDefinition,
];

const START = "<!-- TOOLS:START - generated by scripts/gen-tool-docs.ts -->";
const END = "<!-- TOOLS:END -->";

function unwrapOptional(schema: z.ZodTypeAny): {
	inner: z.ZodTypeAny;
	optional: boolean;
} {
	if (schema instanceof z.ZodOptional) {
		return { inner: schema.unwrap() as z.ZodTypeAny, optional: true };
	}
	return { inner: schema, optional: false };
}

function describeType(schema: z.ZodTypeAny): string {
	if (schema instanceof z.ZodString) return "string";
	if (schema instanceof z.ZodNumber) return "number";
	if (schema instanceof z.ZodBoolean) return "boolean";
	if (schema instanceof z.ZodEnum) {
		const values = (schema as z.ZodEnum<[string, ...string[]]>).options;
		return `enum (${values.map((v) => `\`${v}\``).join(" | ")})`;
	}
	if (schema instanceof z.ZodArray) {
		const element = (schema as z.ZodArray<z.ZodTypeAny>).element;
		return `array of ${describeType(element)}`;
	}
	if (schema instanceof z.ZodObject) return "object";
	return "value";
}

function renderField(name: string, schema: z.ZodTypeAny, indent = ""): string {
	const { inner, optional } = unwrapOptional(schema);
	const description = (inner.description ?? schema.description) as
		| string
		| undefined;
	const typeLabel = describeType(inner);
	const optionalLabel = optional ? " (optional)" : "";
	const trailing = description ? ` — ${description}` : "";
	const head = `${indent}- \`${name}\`: ${typeLabel}${optionalLabel}${trailing}`;
	if (inner instanceof z.ZodObject) {
		const shape = (inner as z.ZodObject<Record<string, z.ZodTypeAny>>).shape;
		const children = Object.entries(shape)
			.map(([k, v]) => renderField(k, v, `${indent}  `))
			.join("\n");
		return children ? `${head}\n${children}` : head;
	}
	return head;
}

function renderTool(tool: ToolDefinition): string {
	const lines: string[] = [];
	lines.push(`### ${tool.name}`);
	lines.push("");
	lines.push(tool.description);
	lines.push("");
	const entries = Object.entries(tool.inputSchema);
	if (entries.length === 0) {
		lines.push("Parameters: none");
	} else {
		lines.push("Parameters:");
		for (const [name, schema] of entries) {
			lines.push(renderField(name, schema));
		}
	}
	if (tool.returns) {
		lines.push("");
		lines.push("Returns:");
		lines.push(`- ${tool.returns}`);
	}
	return lines.join("\n");
}

function renderAll(): string {
	return TOOLS.map(renderTool).join("\n\n");
}

function updateReadme(readmePath: string, body: string): string {
	const current = readFileSync(readmePath, "utf8");
	const block = `${START}\n${body}\n${END}`;
	if (!current.includes(START) || !current.includes(END)) {
		throw new Error(
			`README is missing ${START} / ${END} markers. Add them around the existing tool docs.`,
		);
	}
	const pattern = new RegExp(
		`${escapeRegex(START)}[\\s\\S]*?${escapeRegex(END)}`,
	);
	return current.replace(pattern, block);
}

function escapeRegex(s: string): string {
	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
}

function main() {
	const here = dirname(fileURLToPath(import.meta.url));
	const readmePath = resolve(here, "..", "README.md");
	const check = process.argv.includes("--check");

	const next = updateReadme(readmePath, renderAll());
	const current = readFileSync(readmePath, "utf8");

	if (next === current) {
		if (!check) console.log("README tool docs already up to date.");
		return;
	}

	if (check) {
		console.error(
			"README tool docs are out of date. Run `npm run docs` and commit the result.",
		);
		process.exit(1);
	}

	writeFileSync(readmePath, next);
	console.log("README tool docs regenerated.");
}

main();