caldav-mcp
ποΈ A CalDAV Model Context Protocol (MCP) server to expose calendar operations as tools for AI assistants.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/dominik1001/caldav-mcp with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/dominik1001/caldav-mcp'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/dominik1001--caldav-mcp)HTML
<a href="/listings/dominik1001--caldav-mcp"><img src="/api/listings/dominik1001--caldav-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
{
"mcpServers": {
...,
"calendar": {
"command": "npx",
"args": [
"caldav-mcp"
],
"env": {
"CALDAV_BASE_URL": "<CalDAV server URL>",
"CALDAV_USERNAME": "<CalDAV username>",
"CALDAV_PASSWORD": "<CalDAV password>"
}
}
}
}What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md Β· README Β· 287 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # 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)
- Maintained by the team behind Langmail. Want mail, calendar and contacts for your agent over one hosted MCP, with OAuth and nothing to run? β [langmail.me](https://langmail.me/?ref=caldav-mcp)
- Using caldav-mcp? [Tell us how in three minutes](https://tally.so/r/GepQM2?source=readme).
- </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
- ```
- ## Transports
- The server supports two transports, selected at startup:
- - **stdio** (default): JSON-RPC over stdin/stdout, suitable for the standard MCP client configuration shown in [Setup](#setup).
- ```bash
- npx caldav-mcp
- ```
- - **Streamable HTTP** (`--http`): runs as a long-lived server that remote MCP clients connect to at `POST /mcp`. Each request is handled statelessly, and `GET /health` answers `ok` for health checks.
- ```bash
- MCP_AUTH_TOKEN=your-shared-secret npx caldav-mcp --http
- ```
- | Env var | Default | Description |
- |---|---|---|
- | `MCP_HOST` | `127.0.0.1` | Bind address. Set to `0.0.0.0` to listen on all interfaces. |
- | `MCP_PORT` | `PORT`, else `3000` | TCP port to bind. Falls back to `PORT`, which platforms like Cloud Run set. |
- | `MCP_AUTH_TOKEN` | _(unset)_ | When set, requests must send `Authorization: Bearer <MCP_AUTH_TOKEN>`; others get `401`. Required when `MCP_HOST` is not a loopback address. |
- Connect a client, for example Claude Code (`.mcp.json`):
- ```json
- {
- "mcpServers": {
- "calendar": {
- "type": "http",
- "url": "http://127.0.0.1:3000/mcp",
- "headers": { "Authorization": "Bearer your-shared-secret" }
- }
- }
- }
- ```
- Security notes:
- - One server process serves one CalDAV account. Anyone with the token can read and change that calendar.
- - The server speaks plain HTTP. For remote access, put it behind a reverse proxy that terminates TLS.
- - Requests with an `Origin` header are rejected and there is no CORS support, so browser-based clients can't connect directly.
- - When bound to loopback, only `localhost`/`127.0.0.1`/`[::1]` Host headers are accepted, which blocks DNS rebinding.
- ## Docker
- A `Dockerfile` is provided for running the server with the Streamable HTTP transport β useful when hosting the MCP server as a long-running container that remote MCP clients connect to over HTTP, rather than spawning the binary locally via stdio.
- ```bash
- docker build -t caldav-mcp .
- docker run --rm -p 3000:3000 \
- -e CALDAV_BASE_URL=https://your-caldav-server.com/dav \
- -e CALDAV_USERNAME=your-username \
- -e CALDAV_PASSWORD=your-password \
- -e MCP_AUTH_TOKEN=your-shared-secret \
- caldav-mcp
- ```
- The image binds to `0.0.0.0:3000` (or the port in `MCP_PORT`/`PORT`), serves `POST /mcp`, and reports its health from `GET /health`. Because it listens on all interfaces, `MCP_AUTH_TOKEN` is required: without it the container exits at startup (see [Transports](#transports)). The container is not needed for the default stdio setup in [Setup](#setup) above.
- ## Available Tools
- <!-- TOOLS:START - generated by scripts/gen-tool-docs.ts -->
- ### list-calendars
- List all calendars returning both name and absolute URL. Pass a calendar's `url` unchanged as `calendarUrl` to the other tools.
- 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:
- - `calendarUrl`: string
- - `end`: string β End date (ISO 8601)
- - `start`: string β Start date (ISO 8601)
- 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:
- - `calendarUrl`: string
- - `description`: string (optional)
- - `end`: string β End datetime (ISO 8601)
- - `location`: string (optional)
- - `recurrenceRule`: object (optional)
- - `byday`: array of string (optional)
- - `bymonth`: array of number (optional)
- - `bymonthday`: array of number (optional)
- - `count`: number (optional)
- - `freq`: enum (`DAILY` | `WEEKLY` | `MONTHLY` | `YEARLY`) (optional)
- - `interval`: number (optional)
- - `until`: string (optional)
- - `start`: string β Start datetime (ISO 8601)
- - `summary`: string
- - `wholeDay`: boolean (optional) β Create as a whole-day event
- 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:
- - `calendarUrl`: string
- - `description`: string (optional)
- - `end`: string (optional)
- - `location`: string (optional)
- - `recurrenceRule`: object (optional)
- - `byday`: array of string (optional)
- - `bymonth`: array of number (optional)
- - `bymonthday`: array of number (optional)
- - `count`: number (optional)
- - `freq`: enum (`DAILY` | `WEEKLY` | `MONTHLY` | `YEARLY`) (optional)
- - `interval`: number (optional)
- - `until`: string (optional)
- - `start`: string (optional)
- - `summary`: string (optional)
- - `uid`: string β Unique identifier of the event to update (obtained from list-events)
- - `wholeDay`: boolean (optional) β Update whether this is a whole-day event
- Returns:
- - The unique ID of the updated event
- ### delete-event
- Deletes an event in the calendar specified by its URL
- Parameters:
- - `calendarUrl`: string
- - `uid`: string β Unique identifier of the event to delete (obtained from list-events)
- 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
- - `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.
- - `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.
- - `limit`: number (optional) β Max tasks to return (default 50, max 500)
- - `offset`: number (optional) β Tasks to skip (default 0)
- - `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).
- 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:
- - `calendarUrl`: string
- - `description`: string (optional)
- - `due`: string (optional) β Due datetime (ISO 8601)
- - `location`: string (optional)
- - `start`: string (optional) β Start datetime (ISO 8601)
- - `status`: enum (`NEEDS-ACTION` | `COMPLETED` | `IN-PROCESS` | `CANCELLED`) (optional) β Defaults to NEEDS-ACTION when omitted
- - `summary`: string
- 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:
- - `calendarUrl`: string
- - `description`: string (optional)
- - `due`: string (optional)
- - `location`: string (optional)
- - `start`: string (optional)
- - `status`: enum (`NEEDS-ACTION` | `COMPLETED` | `IN-PROCESS` | `CANCELLED`) (optional)
- - `summary`: string (optional)
- - `uid`: string β Unique identifier of the todo to update (from list-todos)
- 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:
- - `calendarUrl`: string
- - `uid`: string β Unique identifier of the todo to complete (from list-todos)
- Returns:
- - The unique ID of the completed todo
- ### delete-todo
- Deletes a task (VTODO) in the calendar specified by its URL
- Parameters:
- - `calendarUrl`: string
- - `uid`: string β Unique identifier of the todo to delete (from list-todos)
- Returns:
- - Confirmation message when the todo is successfully deleted
- <!-- TOOLS:END -->
- ## License
- MIT
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If itβs helped, pass it on.