MCP CalDAV Server

An Model Context Protocol (MCP) server that connects to a CalDAV server (tested with Baikal) to manage calendars and events.

Features

• List Calendars: View all available calendars.
• List Events:
  • Filter by specific calendar or search globally across all calendars.
  • Filter by time range (start/end date).
• Manage Events:
  • Create new events.
  • Update existing events.
  • Delete events.

Prerequisites

• Python 3.14 or higher
• uv (Universal Python Package Manager)

Installation

1. Clone the repository:

   git clone <repository_url>
   cd MCP-CalDAV
   

2. Install dependencies:

   uv sync
   

Configuration

Create a .env file in the root directory with your CalDAV credentials:

CALDAV_URL=http://your-server:port/dav.php
CALDAV_USERNAME=YourUsername
CALDAV_PASSWORD=YourPassword

Usage

Running Manually

Standard I/O (Default)

You can run the server directly using uv. It communicates via standard input/output (stdio), so running it directly in a terminal will just wait for input.

uv run src/server.py

HTTP (SSE)

To run the server over HTTP (Server-Sent Events) - useful for testing with Postman/Inspector or remote access:

uv run uvicorn src.server:mcp.sse_app --host 0.0.0.0 --port 8000

Endpoint: http://localhost:8000/sse

Docker Deployment

You can run the server using Docker and Docker Compose. Environment variables are loaded from the .env file.

Build and Run (STDIO Mode by default):

docker compose up --build

Switching Modes: The container supports two modes via the MCP_MODE environment variable:

• STDIO (default): Runs the script via standard I/O.
• SSE: Runs the HTTP server on port 8000.

To run in SSE mode (e.g., for HTTP access):

docker run -e MCP_MODE=SSE -p 8000:8000 --env-file .env lagortinez/caldev_mcp

Configuring an MCP Client

To use this with an MCP client (like Claude Desktop or another MCP-compatible app), add the following configuration to your client's settings (e.g., claude_desktop_config.json):

{
  "mcpServers": {
    "caldav": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\Users\\LagoWorkStation\\OneDrive\\Documentos\\MCP-CalDAV",
        "run",
        "src/server.py"
      ]
    }
  }
}

Note: Adjust the absolute path to point to your project directory.

Available Tools

• get_current_time()

  • Returns the current local machine time in ISO format.

• list_calendars()

  • Returns a list of all calendars the user has access to.

• list_events(calendar_name=None, start_date=None, end_date=None)

  • Lists events.
  • calendar_name (optional): Name of the calendar. If omitted, searches ALL calendars.
  • start_date (optional): Start of the range (YYYY-MM-DD or ISO).
  • end_date (optional): End of the range.

• create_event(calendar_name, summary, start_time, end_time, description="", all_day=False, recurrence=None)

  • Creates an event.
  • all_day (optional, bool): Set to True for all-day events (start/end times treated as dates).
  • recurrence (optional, str): RRULE string (e.g., FREQ=DAILY;COUNT=10 or FREQ=WEEKLY;BYDAY=MO,WE).

• update_event(calendar_name, event_uid, summary=None, start_time=None, end_time=None, description=None, all_day=None, recurrence=None)

  • Updates an event by UID.
  • all_day (optional, bool): Set to True/False to change event type.
  • recurrence (optional, str): Update the recurrence rule.

• delete_event(calendar_name, event_uid)

  • Deletes an event by UID.