CalDAV MCP Server for AI Assistants

Overview

This project implements a Model Context Protocol (MCP) server that exposes calendar operations over CalDAV as callable tools for AI assistants. Instead of teaching an assistant the details of CalDAV, you run the server alongside a model and let the assistant call high-level calendar tools (list calendars, find free time, create events, etc.). The MCP server translates those tool calls into CalDAV requests and returns normalized responses the assistant can reason about.

That separation simplifies scheduling workflows: assistants can perform robust calendar operations (conflict detection, timezone-aware event creation, event updates and deletions, and sync) without directly speaking CalDAV. This is especially useful for productivity assistants that need to schedule meetings, suggest availability, or synchronize events across user accounts.

Features

• Exposes common calendar operations as MCP tools backed by CalDAV
• Normalized JSON input/output for safe, predictable assistant calls
• Support for listing calendars, events, free/busy queries, create/update/delete events, and basic sync
• Timezone-aware event handling and ISO 8601 timestamps
• Configurable CalDAV credentials and server URL
• Simple HTTP interface suitable for integrating with streaming or tool-based assistant frameworks
• Lightweight and easy to run locally or behind a reverse proxy

Installation / Configuration

Minimum steps to get the server running locally. Adjust commands for your environment.

Clone the repository:

git clone https://github.com/dominik1001/caldav-mcp.git
cd caldav-mcp

Install dependencies (example using Python; adapt if a different runtime is used):

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Configure environment variables (example):

export CALDAV_URL="https://caldav.example.com/"
export CALDAV_USERNAME="alice"
export CALDAV_PASSWORD="s3cret"
export MCP_BIND="0.0.0.0"
export MCP_PORT="8080"
export MCP_JWT_SECRET="change_this_secret"

Or use a YAML config file (config.yaml):

caldav:
  url: "https://caldav.example.com/"
  username: "alice"
  password: "s3cret"

mcp:
  host: "0.0.0.0"
  port: 8080
  jwt_secret: "change_this_secret"

Start the server (example):

python -m caldav_mcp.app --config config.yaml
# or
FLASK_APP=caldav_mcp.app flask run --host 0.0.0.0 --port 8080

Docker (example docker-compose snippet):

version: "3.7"
services:
  caldav-mcp:
    image: dominik1001/caldav-mcp:latest
    environment:
      - CALDAV_URL=https://caldav.example.com/
      - CALDAV_USERNAME=alice
      - CALDAV_PASSWORD=s3cret
      - MCP_PORT=8080
      - MCP_JWT_SECRET=change_this_secret
    ports:
      - "8080:8080"

Security notes:

• Always run behind TLS in production.
• Store credentials and JWT secrets in a secrets manager or environment variables, not in source control.
• Consider limiting access with a reverse-proxy authentication layer.

Available Tools / Resources

The server exposes a set of HTTP endpoints that map to calendar operations. Each tool receives a JSON payload and returns structured JSON. Typical tool names and signatures:

Example: create_event request (curl)

curl -X POST "http://localhost:8080/tools/create_event" \
  -H "Content-Type: application/json" \
  -d '{
    "calendar_id": "primary",
    "start_iso": "2026-05-01T15:00:00+02:00",
    "end_iso": "2026-05-01T16:00:00+02:00",
    "summary": "Project sync",
    "attendees": ["[email protected]"]
  }'

Response (simplified):

{
  "event_id": "uid-12345",
  "calendar_id": "primary",
  "created": "2026-04-10T12:00:00Z"
}

If you integrate this MCP server with a model/assistant, register the tool endpoints and input schemas so the assistant can call them safely.

Use