Give Your AI Real Calendar Superpowers with `mcp-caldav`

MadboneZ — Wed, 14 Jan 2026 09:04:08 +0000

Lately I’ve been playing a lot with the Model Context Protocol (MCP) and one thing quickly became obvious:

it’s cool that an AI can call tools, but it’s a lot cooler when those tools are connected to your real life.

For me, that started with a simple question:

“Can I let my AI actually see and manage my calendar?”

That’s exactly what mcp-caldav does. It’s an MCP server that connects any CalDAV-compatible calendar (Nextcloud, iCloud, FastMail, Yandex, etc.) to your AI tools, so your model can:

List your calendars
Read your schedule
Create events with reminders, attendees, and recurrence
Search or delete events by UID

The project has already made it into the popular awesome-mcp-servers list, which is a nice signal that it’s not just a toy.

In this post I’ll walk through what the project does, how it’s structured, and how you can plug it into your workflow.

Why CalDAV + MCP Is Actually Useful

CalDAV is a standard protocol that a bunch of calendar providers support:

Nextcloud / ownCloud
Apple iCloud
FastMail
Yandex Calendar
Google Calendar (via CalDAV + OAuth)

On the other side, MCP gives LLMs a unified way to call external tools.

mcp-caldav sits right in the middle:

Towards CalDAV – it speaks the calendar language: events, UIDs, RRULEs, attendees, reminders, categories, priorities.
Towards MCP – it exposes a clean set of tools the AI can call to list calendars, create events, fetch events, search, and delete.

That’s enough to enable workflows like:

“What’s on my calendar this week?”
“Create a 30 minute meeting with Alex tomorrow afternoon.”
“Show me all events tagged #deep-work next month.”
“Delete that ‘Test meeting’ we just created.”

Nothing magical, just solid plumbing between your calendar and your AI.

Quick Project Overview

The repo is here again for convenience:

madbonez/caldav-mcp

The structure is intentionally simple:

src/mcp_caldav/
- __init__.py – main entry point / CLI
- server.py – MCP server implementation (tools, protocol wiring)
- client.py – CalDAV client wrapper (auth, HTTP, event (de)serialization)
tests/
- test_server.py, test_client.py – unit tests
- e2e/ – end-to-end tests against a real CalDAV server
pyproject.toml – packaging and dependency config
Makefile – dev commands (make test, make check, etc.)
README.md, USAGE.md, QUICKSTART.md – docs

As a mid-level dev, this is exactly the kind of layout I like: clear entry point, separation between server and client, and a test suite that actually runs.

Under the hood, the project focuses on:

Strict typing – mypy with pretty strict rules
Fast linting/formatting – ruff
Pre-commit hooks – to keep style and checks consistent

Getting `mcp-caldav` Running

The project uses uv for dependency management, but you’re not locked into it.

Option 1: Local dev with `uv` (recommended for hacking)

git clone https://github.com/madbonez/caldav-mcp.git
cd caldav-mcp

uv sync --dev

This will:

Create a .venv
Install runtime + dev dependencies
Generate uv.lock

Then you can run the server with:

uv run mcp-caldav

Option 2: Run via `uvx` (no local install)

If you mainly want to use the server instead of hacking on it:

uvx mcp-caldav

uvx will pull the published package and run it directly.

Option 3: Classic `pip` install

If you’re more comfortable with pip:

pip install -e .
mcp-caldav

Nothing fancy here — just a normal Python CLI entry point.

Wiring Up Your Calendar (CalDAV Config)

mcp-caldav reads configuration from environment variables:

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

Some common endpoints:

Yandex Calendar: https://caldav.yandex.ru/
Google Calendar: https://apidata.googleusercontent.com/caldav/v2/ (requires OAuth)
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/ (usually with an app-specific password)
FastMail: https://caldav.fastmail.com/dav/calendars/user/

One thing worth calling out: Yandex rate limits pretty aggressively — about 60 seconds per MB since 2021. If you’re doing a lot of write operations (create/update/delete), you can hit 504 timeouts. For heavier workloads, Nextcloud or Google tends to behave better. There are more details in PROVIDER_NOTES.md in the repo.

Plugging It into Cursor (or Another MCP Client)

If you’re using Cursor, you can configure mcp-caldav as a global MCP server so the AI can call these tools automatically whenever you ask calendar-related questions.

Using `uvx` (no local checkout)

Your MCP config might look like this:

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

Using a local clone (for development)

If your repo lives at /Users/you/dev/caldav-mcp:

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

After that, Cursor will expose the mcp-caldav tools and the AI can call them behind the scenes when you say things like “What does my Thursday look like?”.

What Tools Does `mcp-caldav` Expose?

Here’s a quick overview of the main tools and how I imagine using them in real life.

Basic operations

caldav_list_calendars

List all calendars you have access to (personal, work, shared, etc.).

Useful when you want the AI to choose a target calendar or help you discover what’s available.
caldav_create_event

Create a new event with:
- title, description, location
- start/end timestamps or duration
- recurrence rules (daily/weekly/monthly/yearly)
- categories/tags
- priority (0–9)
- attendees with statuses
- multiple reminders
caldav_get_events

Fetch events in a date range. Returns:
- UID
- categories, priority
- attendees and their statuses
- recurrence details
- reminders
caldav_get_today_events

All events for today, including all-day entries. Very handy for “What’s on my plate today?” queries.
caldav_get_week_events

Events for the current week, with an option to define whether the week starts “today” or on Monday. Great for weekly planning prompts.

Advanced operations

caldav_get_event_by_uid

Look up a single event by UID. Good for follow-ups like “Show me more details about that last meeting you mentioned.”
caldav_delete_event

Delete an event by UID. Perfect for cleaning up test events or cancelling a meeting programmatically.
caldav_search_events

Search by:
- text (title / description)
- location
- attendees

This is where you can do things like:

“Find all events with ‘performance review’ in the title this year.”
“Show meetings with Alice in the last month.”
“List all events tagged #deep-work next quarter.”

Dev Experience and Code Quality

As someone who cares about code quality but also doesn’t want to spend hours yak-shaving, I really like how the project wires up tooling.

Linting, formatting, typing

ruff – fast linting + formatting
mypy – static type checking
pre-commit – runs checks before you commit

To get everything installed:

uv sync --group dev

Then you can run:

make check      # run all quality checks
make lint       # lint only
make format     # format code
make type-check # type checking
make test       # run tests

Testing

Unit tests:

make test
# or
make test-unit

End-to-end tests (against a real CalDAV server):

Copy .env.e2e.example to .env.e2e and fill in real credentials.
Run:

   make test-e2e

Coverage:

make test-cov        # coverage in terminal
make coverage-html   # nice HTML report in htmlcov/

It’s the kind of setup where you can refactor the client/server code and get quick feedback if you broke something important.

Why It’s in `awesome-mcp-servers`

The awesome-mcp-servers list curates high-quality MCP servers. mcp-caldav fits nicely there because:

It connects an AI to real-world data (your calendar) using a standard protocol.
The codebase is clean, reasonably small, and easy to navigate.
It has a good testing story (unit + E2E).
Docs are actually helpful (README.md, USAGE.md, QUICKSTART.md, PROVIDER_NOTES.md).

If you’re thinking about writing your own MCP server, this repo is a nice example of:

How to separate transport (MCP) from domain logic (CalDAV client).
How to design a small but expressive tool surface.
How to plug into existing infrastructure (CalDAV servers) without reinventing everything.

Wrapping Up

If you want your AI to do more than just chat and actually work with your schedule, mcp-caldav is a solid starting point:

It speaks a standard protocol (CalDAV).
It exposes well-defined MCP tools.
It’s already battle-tested enough to land in awesome-mcp-servers.

You can check it out here:

https://github.com/madbonez/caldav-mcp

If you end up wiring it into your own setup or extending it (e.g., adding update/patch operations or richer search), that’s exactly the kind of thing I’d expect from someone building serious MCP-based workflows.

DEV Community: MadboneZ