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:

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:

1. Open Cursor Settings → Features → MCP Servers → + Add new global MCP server
2. 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": "[email protected]",
        "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 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.