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

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

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):

1. Copy .env.e2e.example to .env.e2e and fill in real credentials.
2. 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.