caldav-mcp

Dale un calendario a tu asistente de IA. Un servidor MCP que proporciona acceso de lectura/escritura a cualquier calendario compatible con CalDAV — Nextcloud, Radicale, Baikal, ownCloud, iCloud, Fastmail y más — mediante 14 herramientas específicas.

¿Por qué caldav-mcp?

Related MCP server: mcp-labrat

Dónde destaca

• Gestión de calendario impulsada por IA — Permite a Claude, Codex o cualquier cliente MCP crear, actualizar, buscar y eliminar eventos mediante lenguaje natural.

• Acceso multi-tenant — Envía diferentes cabeceras X-Caldav-* por petición para acceder a diferentes cuentas CalDAV desde una única instancia del servidor.

• Automatización de calendario autoalojado — Se combina con tu servidor Nextcloud, Radicale o Baikal existente. Sin dependencia de la nube.

• Despliegues empresariales / de equipo — Centralizado, sin estado, contenedorizado. Despliega detrás de un proxy inverso, escala horizontalmente, rota credenciales sin tiempo de inactividad.

Inicio rápido

# 1. Clone the repo
git clone https://git.gelse.net/werner/caldav-mcp.git && cd caldav-mcp

# 2. Create your .env file
cp .env.example .env
# Edit .env — at minimum set CALDAV_MCP_API_KEY, CALDAV_URL, CALDAV_USERNAME, CALDAV_PASSWORD

# 3. Launch
docker compose up -d

# 4. Verify
curl -s http://localhost:8600/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Caldav-Url: https://cloud.example.com/remote.php/dav/calendars/user/" \
  -H "X-Caldav-Username: user" \
  -H "X-Caldav-Password: app-password" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1"}}}'

El servidor ahora es accesible en http://localhost:8600/mcp (HTTP Streamable).

Herramientas

El servidor expone 14 herramientas MCP en tres categorías.

Consultas (solo lectura)

Mutaciones (escritura)

Asistentes

Despliegue

Docker

El proyecto incluye un Dockerfile multi-etapa:

1. Etapa de construcción — instala las dependencias de Python desde requirements.txt en un prefijo limpio.

2. Etapa de ejecución — copia los paquetes precompilados en una imagen Alpine mínima, se ejecuta como usuario no root app, expone el puerto 8080.

docker build -t caldav-mcp:latest .
docker run -p 8600:8080 \
  -e CALDAV_MCP_API_KEY=YOUR_KEY \
  -e CALDAV_URL=https://cloud.example.com/remote.php/dav/calendars/user/ \
  -e CALDAV_USERNAME=user \
  -e CALDAV_PASSWORD=app-password \
  caldav-mcp:latest

Docker Compose

docker-compose.yaml mapea el puerto del host 8600 al puerto del contenedor 8080 y lee las variables de entorno de un archivo .env local:

services:
  caldav-mcp:
    build: .
    image: caldav-mcp:latest
    restart: unless-stopped
    ports:
      - "8600:8080"
    environment:
      CALDAV_MCP_API_KEY: "${CALDAV_MCP_API_KEY:-}"
      TZ: Europe/Vienna

docker compose up -d

También está disponible un docker-compose.test.yaml para pruebas de integración — incluye un servidor CalDAV Radicale.

TLS / HTTPS

El servidor admite TLS integrado sin proxy inverso. Establece estas variables de entorno para habilitar HTTPS directamente:

CALDAV_MCP_TLS_CERT=/path/to/cert.pem
CALDAV_MCP_TLS_KEY=/path/to/key.pem
CALDAV_MCP_TLS_CA_BUNDLE=/path/to/ca.pem   # optional

Cuando TLS está habilitado, el servidor escucha en HTTPS. Cuando no está configurado, ejecútalo detrás de un proxy inverso (Traefik, Caddy, nginx) que termine TLS.

Autenticación

Dos capas independientes — ambas opcionales pero recomendadas.

Capa 1: Autenticación del endpoint MCP

Cuando CALDAV_MCP_API_KEY está configurada, cada petición al endpoint /mcp debe incluir una de:

• Authorization: Bearer <token>

• X-Api-Key: <token>

El token se compara usando comparación en tiempo constante para prevenir ataques de canal lateral por tiempo. Los intentos fallidos se rastrean por IP de cliente usando un limitador de velocidad de ventana deslizante con retroceso exponencial.

Cuando CALDAV_MCP_API_KEY no está configurada, el endpoint está abierto — no lo expongas a Internet público sin autenticación.

Capa 2: Credenciales CalDAV

Las credenciales CalDAV se resuelven por petición:

1. Cabeceras HTTP (preferidas): X-Caldav-Url, X-Caldav-Username, X-Caldav-Password

2. Variables de entorno (respaldo): CALDAV_URL, CALDAV_USERNAME, CALDAV_PASSWORD

Las cabeceras HTTP tienen prioridad. Esto permite uso multi-tenant — diferentes clientes pueden apuntar a diferentes cuentas CalDAV sin reiniciar el servidor.

Configuración

Toda la configuración se realiza mediante variables de entorno, validadas al inicio con Pydantic.

Servidor

CalDAV

Limitación de velocidad

TLS

Registro

Seguridad

• Coloca el servidor detrás de un proxy inverso que termine TLS, o habilita TLS integrado.

• Establece una CALDAV_MCP_API_KEY fuerte.

• Restringe el acceso a nivel de red/firewall a hosts de confianza o una VPN.

• Prefiere enlazar a 127.0.0.1 a menos que necesites explícitamente acceso remoto.

• Nunca coloques contraseñas de aplicación CalDAV en configuración pública o registros.

Desarrollo

Comandos

make test           # Run unit tests
make test-integration  # Run integration tests (requires docker-compose.test.yaml)
make test-performance  # Run performance benchmarks
make lint           # Lint with ruff (check + format)
make typecheck      # Type check with mypy
make check          # All checks: lint + typecheck + deps-check + test
make deps-check     # Verify pyproject.toml and requirements.txt are in sync
make build          # Build Docker image

Estructura del proyecto

caldav-mcp/
├── server.py                 # Thin entrypoint, launches FastMCP HTTP server
├── caldav_mcp/               # Core package
│   ├── tools/                # MCP tool handlers
│   │   ├── queries.py        #   Read-only tools (7)
│   │   ├── mutations.py      #   Write tools (4)
│   │   └── attendees.py      #   Attendee management (3)
│   ├── auth.py               # Two-layer auth (API key + CalDAV creds)
│   ├── calendar.py           # CalDAV calendar selection & serialization
│   ├── client_cache.py       # Thread-safe LRU cache for DAVClient
│   ├── config.py             # Env var parsing, header constants
│   ├── config_schema.py      # Pydantic startup validation
│   ├── datetime_utils.py     # Date/time parsing, timezone helpers
│   ├── errors.py             # Typed exceptions, ToolResult dataclass
│   ├── event_builder.py      # Pure iCalendar VEVENT construction
│   ├── sanitizers.py         # Input sanitization, field length limits
│   ├── rate_limit.py         # Sliding-window rate limiter
│   ├── audit.py              # Structured JSON audit logging
│   ├── constants.py          # Shared string constants
│   └── types.py              # CalDAVClient Protocol definition
├── tests/                    # Unit, integration, performance
├── docs/                     # Architecture, API, contributing docs
├── Dockerfile                # Multi-stage Docker build
├── docker-compose.yaml       # Production compose
├── docker-compose.test.yaml  # Test compose with Radicale
├── requirements.txt          # Runtime dependencies (pinned)
├── pyproject.toml            # Dev config and dependencies
└── Makefile                  # Build/test shortcuts

Dependencias

Solución de problemas

Preguntas frecuentes

P: ¿Puedo usar esto con varias cuentas CalDAV? R: Sí: envía diferentes cabeceras X-Caldav-Url / X-Caldav-Username / X-Caldav-Password por solicitud. La caché del cliente se basa en (url, username).

P: ¿Qué servidores CalDAV son compatibles? R: Cualquier servidor que implemente el estándar CalDAV: Nextcloud, ownCloud, iCloud, Fastmail, Baikal, Radicale y otros.

P: ¿El token de API se transmite de forma segura? R: Solo cuando se usa HTTPS. Habilita TLS integrado o coloca el servidor detrás de un proxy inverso que termine TLS.

P: ¿Cómo genero una contraseña de aplicación CalDAV? R: Depende de tu proveedor. Nextcloud: Configuración → Seguridad → Contraseñas de aplicación. iCloud: Usa una contraseña específica de la aplicación desde appleid.apple.com.

P: ¿Puedo usar esto a través de stdio en lugar de HTTP? R: El servidor actual solo usa transporte HTTP Streamable. Para usar stdio, modifica server.py para llamar a mcp.run() en lugar de mcp.run_http_async().

Licencia

MIT