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

Source: Dev.to

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

TL;DR

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

mcp‑caldav is an MCP server that bridges any CalDAV‑compatible calendar (Nextcloud, iCloud, FastMail, Yandex, etc.) to your AI tools. The AI can then:

• List calendars
• Read the schedule
• Create events (reminders, attendees, recurrence)
• Search or delete events by UID

The project is already listed in the popular awesome‑mcp‑servers collection, proving it’s more than a toy.

What the Project Does

Example Workflows

• “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.

Repository Layout

caldav-mcp/
├─ src/
│   └─ mcp_caldav/
│       ├─ __init__.py      # main entry point / CLI
│       ├─ server.py        # MCP server (tools, protocol wiring)
│       └─ client.py        # CalDAV client wrapper (auth, HTTP, (de)serialization)
├─ tests/
│   ├─ test_server.py
│   └─ test_client.py
├─ e2e/                     # end‑to‑end tests against a real CalDAV server
├─ pyproject.toml          # packaging & dependency config
├─ Makefile                # dev commands (make test, make check, …)
├─ README.md
├─ USAGE.md
└─ QUICKSTART.md

A clean, mid‑level‑dev‑friendly layout: clear entry point, separation of concerns, and a real test suite.

Core Design Points

• Strict typing – mypy with strict rules
• Fast linting/formatting – ruff
• Pre‑commit hooks – keep style & checks consistent

Running mcp‑caldav

Using uv (recommended)

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

# Install runtime + dev deps, create .venv, generate uv.lock
uv sync --dev

Run the server:

uv run mcp-caldav          # from a local checkout

Or run the published package without a checkout:

uvx mcp-caldav

Using pip

pip install -e .
mcp-caldav

All approaches expose a normal Python CLI entry point.

Configuration

The server reads its settings from environment variables:

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

Common CalDAV Endpoints

Note: Yandex imposes aggressive rate limits (≈ 60 s per MB). Heavy write workloads may hit 504 timeouts. For higher throughput, prefer Nextcloud or Google. See PROVIDER_NOTES.md for details.

Integrating with Cursor (or any MCP‑aware client)

Add mcp‑caldav as a global MCP server so the AI can call calendar tools automatically.

Using uvx (no local checkout)

{
  "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 checkout

{
  "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 configuring, Cursor (or any MCP‑enabled client) will expose the following tools to the LLM.

Exposed MCP Tools

These tools give you a full CRUD interface to any CalDAV calendar from within your LLM‑driven workflow.

Quick Recap

1. Clone / install the repo (uv or pip).
2. Set environment variables for your CalDAV server.
3. Run mcp-caldav.
4. Configure your MCP client (Cursor, etc.) to point at the server.
5. Ask your AI natural‑language calendar questions – it will call the appropriate MCP tool under the hood.

Enjoy a calendar that truly lives in your AI’s brain!

CalDAV MCP Tools Overview

caldav_get_week_events

Returns events for the current week.

• 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 its UID.

Use case: “Show me more details about that last meeting you mentioned.”

caldav_delete_event

Delete an event by its UID.

Use case: Cleaning up test events or cancelling a meeting programmatically.

caldav_search_events

Search by:

• text (title / description)
• location
• attendees

Examples:

• “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.”

Development Tooling

The project wires up a solid quality‑assurance stack:

Getting Started

# Install all dependencies (including dev group)
uv sync --group dev

Common Make Commands

End‑to‑End Test Setup

1. Copy the example env file:

   cp .env.e2e.example .env.e2e

2. Fill in real CalDAV credentials in .env.e2e.

3. Run the tests:

   make test-e2e

awesome-mcp-servers Listing

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

• Connects an AI to real‑world data (your calendar) via a standard protocol.
• Clean, reasonably small codebase that’s easy to navigate.
• Good testing story (unit + E2E).
• Helpful documentation (README.md, USAGE.md, QUICKSTART.md, PROVIDER_NOTES.md).

Why Use This Repo as a Reference?

• Separation of concerns: Transport (MCP) vs. domain logic (CalDAV client).
• Expressive tool surface: Small but powerful API.
• Plug‑and‑play: Works with existing CalDAV servers without reinventing the wheel.

If you want your AI to do more than just chat—e.g., actually manage your schedule—mcp-caldav is a solid starting point:

• Speaks a standard protocol (CalDAV).
• Exposes well‑defined MCP tools.
• Battle‑tested enough to be featured in awesome-mcp-servers.

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

Feel free to wire it into your own setup or extend it (e.g., adding update/patch operations or richer search). That’s exactly the kind of work expected from someone building serious MCP‑based workflows.