Skip to content
Back to search

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.

Checked today

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/dominik1001--caldav-mcp/badge.svg)](/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

i

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.

  1. # caldav-mcp
  2. <div align="center">
  3. πŸ—“οΈ A CalDAV Model Context Protocol (MCP) server to expose calendar operations as tools for AI assistants.
  4. [![Release](https://github.com/dominik1001/caldav-mcp/actions/workflows/release.yml/badge.svg)](https://github.com/dominik1001/caldav-mcp/actions/workflows/release.yml)
  5. [![npm version](https://badge.fury.io/js/caldav-mcp.svg)](https://www.npmjs.com/package/caldav-mcp)
  6. [![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](https://choosealicense.com/licenses/mit/)
  7. [![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)
  8. [![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-purple.svg)](https://modelcontextprotocol.io)
  9. [![semantic-release: angular](https://img.shields.io/badge/semantic--release-angular-e10079?logo=semantic-release)](https://github.com/semantic-release/semantic-release)
  10. 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)
  11. Using caldav-mcp? [Tell us how in three minutes](https://tally.so/r/GepQM2?source=readme).
  12. </div>
  13. ## ✨ Features
  14. - Connect to CalDAV servers
  15. - List calendars
  16. - List calendar events within a specific timeframe
  17. - Create calendar events
  18. - Update calendar events
  19. - Delete calendar events by UID
  20. ## Setup
  21. ```
  22. {
  23. "mcpServers": {
  24. ...,
  25. "calendar": {
  26. "command": "npx",
  27. "args": [
  28. "caldav-mcp"
  29. ],
  30. "env": {
  31. "CALDAV_BASE_URL": "<CalDAV server URL>",
  32. "CALDAV_USERNAME": "<CalDAV username>",
  33. "CALDAV_PASSWORD": "<CalDAV password>"
  34. }
  35. }
  36. }
  37. }
  38. ```
  39. ## Development
  40. ### Quick Start
  41. Run the MCP server in development mode with auto-reload:
  42. ```bash
  43. npm run dev
  44. ```
  45. This will run the TypeScript code directly with watch mode and automatically load environment variables from `.env`.
  46. ### Manual Build
  47. Alternatively, you can compile TypeScript to JavaScript and run it:
  48. 1. Compile:
  49. ```bash
  50. npx tsc
  51. ```
  52. 2. Run:
  53. ```bash
  54. node dist/index.js
  55. ```
  56. ## Transports
  57. The server supports two transports, selected at startup:
  58. - **stdio** (default): JSON-RPC over stdin/stdout, suitable for the standard MCP client configuration shown in [Setup](#setup).
  59. ```bash
  60. npx caldav-mcp
  61. ```
  62. - **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.
  63. ```bash
  64. MCP_AUTH_TOKEN=your-shared-secret npx caldav-mcp --http
  65. ```
  66. | Env var | Default | Description |
  67. |---|---|---|
  68. | `MCP_HOST` | `127.0.0.1` | Bind address. Set to `0.0.0.0` to listen on all interfaces. |
  69. | `MCP_PORT` | `PORT`, else `3000` | TCP port to bind. Falls back to `PORT`, which platforms like Cloud Run set. |
  70. | `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. |
  71. Connect a client, for example Claude Code (`.mcp.json`):
  72. ```json
  73. {
  74. "mcpServers": {
  75. "calendar": {
  76. "type": "http",
  77. "url": "http://127.0.0.1:3000/mcp",
  78. "headers": { "Authorization": "Bearer your-shared-secret" }
  79. }
  80. }
  81. }
  82. ```
  83. Security notes:
  84. - One server process serves one CalDAV account. Anyone with the token can read and change that calendar.
  85. - The server speaks plain HTTP. For remote access, put it behind a reverse proxy that terminates TLS.
  86. - Requests with an `Origin` header are rejected and there is no CORS support, so browser-based clients can't connect directly.
  87. - When bound to loopback, only `localhost`/`127.0.0.1`/`[::1]` Host headers are accepted, which blocks DNS rebinding.
  88. ## Docker
  89. 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.
  90. ```bash
  91. docker build -t caldav-mcp .
  92. docker run --rm -p 3000:3000 \
  93. -e CALDAV_BASE_URL=https://your-caldav-server.com/dav \
  94. -e CALDAV_USERNAME=your-username \
  95. -e CALDAV_PASSWORD=your-password \
  96. -e MCP_AUTH_TOKEN=your-shared-secret \
  97. caldav-mcp
  98. ```
  99. 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.
  100. ## Available Tools
  101. <!-- TOOLS:START - generated by scripts/gen-tool-docs.ts -->
  102. ### list-calendars
  103. List all calendars returning both name and absolute URL. Pass a calendar's `url` unchanged as `calendarUrl` to the other tools.
  104. Parameters: none
  105. Returns:
  106. - List of all available calendars
  107. ### list-events
  108. List all events between start and end date in the calendar specified by its URL
  109. Parameters:
  110. - `calendarUrl`: string
  111. - `end`: string β€” End date (ISO 8601)
  112. - `start`: string β€” Start date (ISO 8601)
  113. Returns:
  114. - A list of events that fall within the given timeframe, each containing `uid`, `summary`, `start`, `end`, and optionally `description` and `location`
  115. ### create-event
  116. 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.
  117. Parameters:
  118. - `calendarUrl`: string
  119. - `description`: string (optional)
  120. - `end`: string β€” End datetime (ISO 8601)
  121. - `location`: string (optional)
  122. - `recurrenceRule`: object (optional)
  123. - `byday`: array of string (optional)
  124. - `bymonth`: array of number (optional)
  125. - `bymonthday`: array of number (optional)
  126. - `count`: number (optional)
  127. - `freq`: enum (`DAILY` | `WEEKLY` | `MONTHLY` | `YEARLY`) (optional)
  128. - `interval`: number (optional)
  129. - `until`: string (optional)
  130. - `start`: string β€” Start datetime (ISO 8601)
  131. - `summary`: string
  132. - `wholeDay`: boolean (optional) β€” Create as a whole-day event
  133. Returns:
  134. - The unique ID of the created event
  135. ### update-event
  136. 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.
  137. Parameters:
  138. - `calendarUrl`: string
  139. - `description`: string (optional)
  140. - `end`: string (optional)
  141. - `location`: string (optional)
  142. - `recurrenceRule`: object (optional)
  143. - `byday`: array of string (optional)
  144. - `bymonth`: array of number (optional)
  145. - `bymonthday`: array of number (optional)
  146. - `count`: number (optional)
  147. - `freq`: enum (`DAILY` | `WEEKLY` | `MONTHLY` | `YEARLY`) (optional)
  148. - `interval`: number (optional)
  149. - `until`: string (optional)
  150. - `start`: string (optional)
  151. - `summary`: string (optional)
  152. - `uid`: string β€” Unique identifier of the event to update (obtained from list-events)
  153. - `wholeDay`: boolean (optional) β€” Update whether this is a whole-day event
  154. Returns:
  155. - The unique ID of the updated event
  156. ### delete-event
  157. Deletes an event in the calendar specified by its URL
  158. Parameters:
  159. - `calendarUrl`: string
  160. - `uid`: string β€” Unique identifier of the event to delete (obtained from list-events)
  161. Returns:
  162. - Confirmation message when the event is successfully deleted
  163. ### list-todos
  164. 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.
  165. Parameters:
  166. - `calendarUrl`: string
  167. - `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.
  168. - `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.
  169. - `limit`: number (optional) β€” Max tasks to return (default 50, max 500)
  170. - `offset`: number (optional) β€” Tasks to skip (default 0)
  171. - `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).
  172. Returns:
  173. - 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`.
  174. ### create-todo
  175. 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.
  176. Parameters:
  177. - `calendarUrl`: string
  178. - `description`: string (optional)
  179. - `due`: string (optional) β€” Due datetime (ISO 8601)
  180. - `location`: string (optional)
  181. - `start`: string (optional) β€” Start datetime (ISO 8601)
  182. - `status`: enum (`NEEDS-ACTION` | `COMPLETED` | `IN-PROCESS` | `CANCELLED`) (optional) β€” Defaults to NEEDS-ACTION when omitted
  183. - `summary`: string
  184. Returns:
  185. - The unique ID of the created todo
  186. ### update-todo
  187. 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.
  188. Parameters:
  189. - `calendarUrl`: string
  190. - `description`: string (optional)
  191. - `due`: string (optional)
  192. - `location`: string (optional)
  193. - `start`: string (optional)
  194. - `status`: enum (`NEEDS-ACTION` | `COMPLETED` | `IN-PROCESS` | `CANCELLED`) (optional)
  195. - `summary`: string (optional)
  196. - `uid`: string β€” Unique identifier of the todo to update (from list-todos)
  197. Returns:
  198. - The unique ID of the updated todo
  199. ### complete-todo
  200. Marks a task (VTODO) as done. Sets its status to COMPLETED and records the completion time.
  201. Parameters:
  202. - `calendarUrl`: string
  203. - `uid`: string β€” Unique identifier of the todo to complete (from list-todos)
  204. Returns:
  205. - The unique ID of the completed todo
  206. ### delete-todo
  207. Deletes a task (VTODO) in the calendar specified by its URL
  208. Parameters:
  209. - `calendarUrl`: string
  210. - `uid`: string β€” Unique identifier of the todo to delete (from list-todos)
  211. Returns:
  212. - Confirmation message when the todo is successfully deleted
  213. <!-- TOOLS:END -->
  214. ## License
  215. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.