caldav-mcp
by langmail
README.md
# caldav-mcp
<div align="center">
šļø A CalDAV Model Context Protocol (MCP) server to expose calendar operations as tools for AI assistants.
[](https://github.com/langmail/caldav-mcp/actions/workflows/release.yml)
[](https://www.npmjs.com/package/caldav-mcp)
[](https://choosealicense.com/licenses/mit/)
[](https://biomejs.dev)
[](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
- List tasks (VTODOs), open ones by default or filtered by status
- Create and update tasks, with optional due and start dates
- Mark tasks as completed
- Delete tasks 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
This server cannot be deployed
Maintenance
ActivityActive
ResponsivenessLimited data