io.github.dominik1001/caldav-mcp
CalDAV calendar operations (list, create, update, delete events) as MCP tools.
Open source Open in the app JSON README (API)
About
CalDAV calendar operations (list, create, update, delete events) as MCP tools.
Details
- Kind
- MCP servers
- Topic
- Productivity
- Publisher
- dominik1001
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.9.0
- Stars
- 99
- Forks
- 32
- Open pull requests
- 8
- Last push
- 2026-09-07T10:32:59Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:02:43
- Updated
- 2026-08-29 03:02:43
- Origin id
io.github.dominik1001/caldav-mcp
README
# caldav-mcp
<div align="center">
🗓️ A CalDAV Model Context Protocol (MCP) server to expose calendar operations as tools for AI assistants.
[](https://github.com/dominik1001/caldav-mcp/actions/workflows/release.yml)
[](https://www.npmjs.com/package/caldav-mcp)
[](https://choosealicense.com/licenses/mit/)
[](https://github.com/prettier/prettier)
[](https://modelcontextprotocol.io)
[](https://github.com/semantic-release/semantic-release)
</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:
```bash
npx tsc
```
2. Run:
```bash
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