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.lockfile
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 uv sync or pip install):
{
"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 sync):
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 calendarscaldav_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 todaycaldav_get_week_events- Get events for the week
Advanced Operations:
caldav_get_event_by_uid- Get a specific event by its UIDcaldav_delete_event- Delete an event by UIDcaldav_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.