Radicale CalDAV MCP Server

A Model Context Protocol (MCP) server built with FastMCP / the official MCP Python SDK that bridges LLM agents (such as Nous Hermes, Claude, OpenAI) to a self-hosted Radicale CalDAV calendar and task manager.

---

Features

📅 Calendar Events (VEVENT)

• get_events: Query events within date/time ranges with optional keyword search across summary, description, and location.
• get_free_busy_slots: Calculate open, unbooked time slots during configurable business hours (e.g. 9:00 AM - 5:00 PM) in any IANA timezone.
• create_event: Schedule new events with automatic ISO validation, attendee invitations, and overlap/conflict detection.
• update_event: Modify existing events by UID without overwriting untouched fields.
• delete_event: Remove events by UID.

📝 Tasks & To-Dos (VTODO)

• list_todos: Fetch pending or completed tasks filtered by status (NEEDS-ACTION, COMPLETED, IN-PROCESS, CANCELLED, ALL).
• create_todo: Create tasks with due dates, priority levels (1-9), and descriptions.
• complete_todo: Mark tasks as completed with automatic completion timestamps.

🚀 Transports & Deployment

• STDIO Transport: Default transport for local execution (e.g. Claude Desktop, local agents).
• SSE (Server-Sent Events) Transport: Over HTTP for remote, always-on deployments (e.g. Coolify, Docker).

---

Configuration

Configure the server via environment variables or a .env file:

Variable	Default	Description
RADICALE_BASE_URL	http://localhost:5232	Base URL to Radicale (e.g. https://radicale.dubblu.app)
RADICALE_USERNAME	mvela581	CalDAV username
RADICALE_PASSWORD	""	CalDAV password
RADICALE_CALENDAR_SLUG	seuspeptides	Target calendar slug / collection name
DEFAULT_TIMEZONE	America/New_York	Default IANA timezone
MCP_TRANSPORT	stdio	Transport protocol: stdio or sse
MCP_HOST	0.0.0.0	Host interface for SSE mode
MCP_PORT	8000	Port number for SSE mode

---

Local Quickstart

1. Installation

# Clone and enter directory
cd radicale-mcp-server

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

2. Configure Environment

Copy .env.example to .env and set your credentials:

cp .env.example .env

3. Run Locally

STDIO Mode (Local Pipe)

python server.py --stdio

SSE Mode (HTTP Server)

python server.py --sse --host 0.0.0.0 --port 8000

4. Run Test Client

# Test via STDIO
python test_client.py --mode stdio

# Test via SSE (when server is running)
python test_client.py --mode sse --sse-url http://localhost:8000/sse

5. Run Automated Tests

pytest -v

---

Coolify Deployment

Deploy the MCP server on Coolify with zero configuration:

1. Create a new service in Coolify: Docker Compose or Dockerfile.
2. Point it to this repository or paste the docker-compose.yml.
3. Set the following environment variables in Coolify UI:
   • RADICALE_BASE_URL=https://radicale.dubblu.app
   • RADICALE_USERNAME=mvela581
   • RADICALE_PASSWORD=your_password
   • RADICALE_CALENDAR_SLUG=seuspeptides
   • DEFAULT_TIMEZONE=America/New_York
   • MCP_TRANSPORT=sse
   • MCP_PORT=8000
4. Expose port 8000 via Coolify reverse proxy with your domain (e.g. https://mcp-calendar.yourdomain.com).
5. Your SSE endpoint will be accessible at:

   https://mcp-calendar.yourdomain.com/sse
   

---

LLM Agent Integration (Nous Hermes / Claude Desktop)

Claude Desktop Configuration

Add the following to your claude_desktop_config.json:

Local STDIO:

{
  "mcpServers": {
    "radicale_calendar": {
      "command": "/path/to/radicale-mcp-server/.venv/bin/python",
      "args": ["/path/to/radicale-mcp-server/server.py", "--stdio"],
      "env": {
        "RADICALE_BASE_URL": "https://radicale.dubblu.app",
        "RADICALE_USERNAME": "mvela581",
        "RADICALE_PASSWORD": "your_password",
        "RADICALE_CALENDAR_SLUG": "seuspeptides",
        "DEFAULT_TIMEZONE": "America/New_York"
      }
    }
  }
}

Remote SSE (Coolify):

{
  "mcpServers": {
    "radicale_calendar": {
      "url": "https://mcp-calendar.yourdomain.com/sse"
    }
  }
}

Nous Hermes Agent Integration

Tool definitions are auto-generated from docstrings with type specifications. Sample prompt usage:

{
  "name": "get_free_busy_slots",
  "arguments": {
    "start_date": "2026-08-26",
    "end_date": "2026-08-28",
    "slot_duration_minutes": 30,
    "working_hours_start": 9,
    "working_hours_end": 17,
    "timezone": "America/New_York"
  }
}

---

License

MIT