Which integrations are available for this server?

Provides CalDAV protocol integration with [Google Calendar](/mcp/servers/integrations/google-calendar), enabling tools to list calendars, create and manage events with reminders, attendees, recurrence patterns, and search functionality. Provides CalDAV protocol integration with Apple [iCloud](/mcp/servers/integrations/icloud) Calendar, enabling tools to list calendars, create and manage events with reminders, attendees, recurrence patterns, and search functionality. Provides CalDAV protocol integration with [Nextcloud](/mcp/servers/integrations/nextcloud) Calendar, enabling tools to list calendars, create and manage events with reminders, attendees, recurrence patterns, and search functionality. Provides CalDAV protocol integration with [ownCloud](/mcp/servers/integrations/owncloud) Calendar, enabling tools to list calendars, create and manage events with reminders, attendees, recurrence patterns, and search functionality.

MCP CalDAV Server

Universal MCP server for CalDAV protocol integration. Works with any CalDAV-compatible calendar server including Yandex Calendar, Google Calendar (via CalDAV), Nextcloud, ownCloud, Apple iCloud, and others.

📖 Quick Start: See QUICKSTART.md for a quick guide to get started with uv. 🔧 Cursor Setup: See CURSOR_SETUP.md for detailed Cursor IDE configuration instructions.

Features

List available calendars
Create calendar events with reminders and attendees
Get events for today, week, or custom date range
Works with any CalDAV-compatible server (Yandex, Google, Nextcloud, ownCloud, iCloud, etc.)

Installation

Using uv (Recommended)

First, install uv if you haven't already:

macOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Then install the project:

uv sync --dev

This will:

Create a virtual environment (.venv)
Install all dependencies including dev dependencies
Generate a uv.lock file

Using uvx (Run without installation)

You can also run the server directly without installing it:

uvx mcp-caldav

Using pip

pip install -e .

Configuration

Set the following environment variables:

export CALDAV_URL="https://caldav.example.com/" export CALDAV_USERNAME="your-username" export CALDAV_PASSWORD="your-password"

CalDAV Server URLs

Common CalDAV server URLs:

Yandex Calendar: https://caldav.yandex.ru/
Google Calendar: https://apidata.googleusercontent.com/caldav/v2/ (requires OAuth setup)
Nextcloud: https://your-domain.com/remote.php/dav/calendars/username/
ownCloud: https://your-domain.com/remote.php/dav/calendars/username/
Apple iCloud: https://caldav.icloud.com/ (requires app-specific password)
FastMail: https://caldav.fastmail.com/dav/calendars/user/

Note: Some servers require app-specific passwords instead of regular passwords. Check your calendar provider's documentation for CalDAV setup instructions.

Usage

IDE Integration (Cursor)

To use this MCP server in Cursor:

Open Cursor Settings → Features → MCP Servers → + Add new global MCP server
Add the following configuration:

Using uvx (Recommended - no installation needed):

{ "mcpServers": { "mcp-caldav": { "command": "uvx", "args": ["mcp-caldav"], "env": { "CALDAV_URL": "https://caldav.example.com/", "CALDAV_USERNAME": "your-username", "CALDAV_PASSWORD": "your-password" } } } }

Using local installation (after

{ "mcpServers": { "mcp-caldav": { "command": "mcp-caldav", "env": { "CALDAV_URL": "https://caldav.example.com/", "CALDAV_USERNAME": "your-username", "CALDAV_PASSWORD": "your-password" } } } }

Using local development version:

{ "mcpServers": { "mcp-caldav": { "command": "uv", "args": ["run", "--directory", "/path/to/caldav", "mcp-caldav"], "env": { "CALDAV_URL": "https://caldav.example.com/", "CALDAV_USERNAME": "your-username", "CALDAV_PASSWORD": "your-password" } } } }

Example for Yandex Calendar:

{ "mcpServers": { "mcp-caldav": { "command": "uvx", "args": ["mcp-caldav"], "env": { "CALDAV_URL": "https://caldav.yandex.ru/", "CALDAV_USERNAME": "your-username@yandex.ru", "CALDAV_PASSWORD": "your-app-password" } } } }

⚠️ Note: Yandex Calendar has aggressive rate limiting (60 seconds per MB since 2021). Write operations (create/update/delete) may experience 504 timeouts, so space out requests and introduce manual delays. For write-heavy workloads, consider using Google Calendar or Nextcloud instead. See PROVIDER_NOTES.md for details.
Testing status: End-to-end tests currently run only against Yandex Calendar. Other CalDAV providers follow the same protocol and should work, but they have not been integration-tested yet.

Example for Nextcloud:

{ "mcpServers": { "mcp-caldav": { "command": "uvx", "args": ["mcp-caldav"], "env": { "CALDAV_URL": "https://your-domain.com/remote.php/dav/calendars/username/", "CALDAV_USERNAME": "your-username", "CALDAV_PASSWORD": "your-password" } } } }

As MCP Server

The server can be used with MCP-compatible clients:

Using uv (after

uv run mcp-caldav

Note: uvx works only with published packages from PyPI. For local development, use uv run mcp-caldav after uv sync.

Using pip (after installation):

mcp-caldav

Or with custom options:

uv run mcp-caldav --caldav-url "https://caldav.example.com/" \ --caldav-username "your-username" \ --caldav-password "your-password" \ --verbose

Available Tools

Basic Operations:

caldav_list_calendars - List all available calendars
caldav_create_event - Create a new calendar event (supports recurrence, categories, priority, attendees)
caldav_get_events - Get events for a date range (returns extended fields: UID, categories, priority, attendees, recurrence)
caldav_get_today_events - Get events for today
caldav_get_week_events - Get events for the week

Advanced Operations:

caldav_get_event_by_uid - Get a specific event by its UID
caldav_delete_event - Delete an event by UID
caldav_search_events - Search events by text, attendees, or location

Features Supported:

Recurring events (RRULE) - Daily, Weekly, Monthly, Yearly patterns
Categories/Tags - Organize events with categories
Priority - Set priority levels (0-9, 0 = highest)
Attendees with statuses - Track acceptance status (ACCEPTED/DECLINED/TENTATIVE/NEEDS-ACTION)
Reminders - Multiple reminders per event

Development

Code Quality

This project uses several tools to ensure code quality:

mypy - Static type checking with strict rules
ruff - Fast linting and code formatting
pre-commit - Automatic checks before commits

Run quality checks:

# Install dev dependencies uv sync --group dev # Run all checks make check # Or individually make lint make format make type-check # Or using pre-commit make pre-commit-run

Setup pre-commit hooks:

uv run pre-commit install

See CODE_QUALITY.md for detailed information.

Running Tests

Unit tests (with mocks):

make test # or make test-unit

E2E tests (require real CalDAV server):

# Create .env.e2e file with your credentials, then: make test-e2e

All tests:

make test

With coverage:

make test-cov # Terminal report make coverage-html # HTML report

See tests/e2e/README.md for more details on e2e tests.

Project Structure

caldav/ ├── src/ │ └── mcp_caldav/ │ ├── __init__.py # Main entry point │ ├── server.py # MCP server implementation │ └── client.py # CalDAV client wrapper ├── tests/ │ ├── test_server.py # Server unit tests │ ├── test_client.py # Client unit tests │ └── e2e/ # End-to-end tests with real server │ ├── test_client_e2e.py │ └── conftest.py ├── pyproject.toml # Project configuration ├── Makefile # Development commands └── README.md # This file

License

See LICENSE file for details.

CalDAV MCP Server