caldav-mcp

Дайте вашему ИИ-ассистенту календарь. MCP-сервер, который предоставляет доступ на чтение и запись к любому календарю с поддержкой CalDAV — Nextcloud, Radicale, Baikal, ownCloud, iCloud, Fastmail и другим, — через 14 специализированных инструментов.

Зачем caldav-mcp?

Related MCP server: mcp-labrat

Где это полезно

• Управление календарём с помощью ИИ — Позвольте Claude, Codex или любому MCP-клиенту создавать, обновлять, искать и удалять события через естественный язык.

• Мультитенантный доступ — Отправляйте разные X-Caldav-* заголовки в каждом запросе, чтобы работать с разными учётными записями CalDAV на одном экземпляре сервера.

• Автоматизация календаря на собственном сервере — Работает с уже существующим Nextcloud, Radicale или Baikal. Без привязки к облаку.

• Корпоративные и командные развёртывания — Централизованные, не имеющие состояния, контейнеризированные. Размещайте за обратным прокси, масштабируйте горизонтально, изменяйте учётные данные без простоя.

Быстрый старт

# 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"}}}'

Теперь сервер доступен по адресу http://localhost:8600/mcp (Streamable HTTP).

Инструменты

Сервер предоставляет 14 MCP-инструментов в трёх категориях.

Запросы (только чтение)

Изменения (запись)

Участники

Развёртывание

Docker

Проект поставляется с многоступенчатым Dockerfile:

1. Этап сборки — устанавливает Python-зависимости из requirements.txt в чистый префикс.

2. Этап выполнения — копирование ранее собранные пакеты в минимальный Alpine-образ, работает из-под непривилегированного пользователя app, открывает порт 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 сопоставляет порт хоста 8600 с портом контейнера 8080 и читает переменные окружения из локального файла .env:

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

Также для интеграционных тестов доступен docker-compose.test.yaml — он включает CalDAV-сервер Radicale.

TLS / HTTPS

Сервер поддерживает встроенный TLS без обратного прокси. Используйте следующие переменные окружения для включения HTTPS:

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

Когда TLS включён, сервер слушает HTTPS. Если TLS не настроен, запускайте сервер за обратным прокси (Traefik, Caddy, nginx), который выполняет завершение TLS.

Аутентификация

Два независимых уровня — оба опциональны, но рекомендуются.

Уровень 1: аутентификация конечной точки MCP

Если задан CALDAV_MCP_API_KEY, каждый запрос к конечной точке /mcp должен содержать один из вариантов:

• Authorization: Bearer <token>

• X-Api-Key: <token>

Сравнение токена выполняется за постоянное время, чтобы исключить атаки по вспомогательным каналам, связанным со временем. Неудачные попытки отслеживаются по IP-адресу клиента с помощью скользящего окна с экспоненциальной задержкой.

Если CALDAV_MCP_API_KEY не задан, конечная точка открыта — не публикуйте её в публичный интернет без аутентификации.

Уровень 2: учётные данные CalDAV

Учётные данные CalDAV запрашиваются для каждого запроса:

1. HTTP-заголовки (предпочтительно): X-Caldav-Url, X-Caldav-Username, X-Caldav-Password

2. Переменные окружения (резервный вариант): CALDAV_URL, CALDAV_USERNAME, CALDAV_PASSWORD

HTTP-заголовки имеют приоритет. Это позволяет организовать multi-tenant использование: разные клиенты могут направлять запросы к разным учётным записям CalDAV без перезапуска сервера.

Конфигурация

Вся конфигурация задаётся через переменные окружения и проверяется при запуске с помощью Pydantic.

Сервер

CalDAV

Ограничение частоты запросов

TLS

Логирование

Безопасность

• МВСТАВИТЬ сервер за обратным прокси, который завершает TLS, либо включите встроенный TLS.

• Установите надёжный CALDAV_MCP_API_KEY.

• Ограничьте доступ на уровне сети/межсетевого экрана доверенными хостами или VPN.

• Предпочтительно привязывайте сервер к адресу 127.0.0.1, если явно не нужен удалённый доступ.

• Никогда не помещайте пароли приложений CalDAV в публичную конфигурацию или журналы.

Разработка

Команды

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

Структура проекта

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

Зависимости

Устранение неполадок

FAQ

В: Можно ли использовать это с несколькими учетными записями CalDAV? О: Да — отправляйте разные заголовки X-Caldav-Url / X-Caldav-Username / X-Caldav-Password для каждого запроса. Кэш клиента привязан к паре (url, username).

В: Какие серверы CalDAV поддерживаются? О: Любой сервер, реализующий стандарт CalDAV: Nextcloud, ownCloud, iCloud, Fastmail, Baikal, Radicale и другие.

В: Передается ли API-токен безопасно? О: Только при использовании HTTPS. Включите встроенный TLS или разместите сервер за TLS-terminating обратным прокси.

В: Как сгенерировать пароль приложения CalDAV? О: Зависит от вашего провайдера. Nextcloud: Настройки → Безопасность → Пароли приложений. iCloud: Используйте пароль, специфичный для приложения, с appleid.apple.com.

В: Можно ли использовать это через stdio вместо HTTP? О: Текущий сервер использует только транспорт Streamable HTTP. Чтобы использовать stdio, измените server.py, вызвав mcp.run() вместо mcp.run_http_async().

Лицензия

MIT