# madbonez/caldav-mcp [Health: Active]

**Category:** 💬 Communication  
**Repository:** https://github.com/madbonez/caldav-mcp  
**GitHub Stars:** 14  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/madbonez-caldav-mcp

## Description
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. Supports creating events with recurrence, categories, priority, attendees, reminders, searching events, and retrieving events by UID.

## Tools
Capabilities this server exposes over MCP:

- **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
- **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

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "caldav-mcp": {
    "command": "uvx",
    "args": ["mcp-caldav"],
    "env": {
      "CALDAV_URL": "",
      "CALDAV_USERNAME": "",
      "CALDAV_PASSWORD": ""
    }
  }
}
```

**Requires environment variables:** `CALDAV_URL`, `CALDAV_USERNAME`, `CALDAV_PASSWORD` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation & README

# 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](https://github.com/madbonez/caldav-mcp/blob/HEAD/QUICKSTART.md) for a quick guide to get started with `uv`.
> 🔧 **Cursor Setup**: See [CURSOR_SETUP.md](https://github.com/madbonez/caldav-mcp/blob/HEAD/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:**

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

**Windows:**

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

Then install the project:

```bash
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:

```bash
uvx mcp-caldav
```

### Using pip

```bash
pip install -e .
```

## Configuration

Set the following environment variables:

```bash
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):**

```json
{
  "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`):**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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](https://github.com/madbonez/caldav-mcp/blob/HEAD/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:**

```json
{
  "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`):**

```bash
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):**

```bash
mcp-caldav
```

Or with custom options:

```bash
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:**

```bash
# 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:**

```bash
uv run pre-commit install
```

See [CODE_QUALITY.md](https://github.com/madbonez/caldav-mcp/blob/HEAD/CODE_QUALITY.md) for detailed information.

### Running Tests

**Unit tests (with mocks):**

```bash
make test
# or
make test-unit
```

**E2E tests (require real CalDAV server):**

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

**All tests:**

```bash
make test
```

**With coverage:**

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

See [tests/e2e/README.md](https://github.com/madbonez/caldav-mcp/blob/HEAD/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.