madbonez/caldav-mcp

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:**
**Windows:**
Then install the project:
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:
Using pip
Configuration
Set the following environment variables:
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:
1. Open Cursor Settings → Features → MCP Servers → + Add new global MCP server
2. Add the following configuration:
**Using uvx (Recommended - no installation needed):**
**Using local installation (after uv sync or pip install):**
**Using local development version:**
**Example for Yandex Calendar:**
> **⚠️ 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:**
As MCP Server
The server can be used with MCP-compatible clients:
**Using uv (after uv sync):**
**Note:** uvx works only with published packages from PyPI. For local development, use uv run mcp-caldav after uv sync.
**Using pip (after installation):**
Or with custom options:
Available Tools
**Basic Operations:**
- caldav_list_calendars - List all available calendars