Servidor MCP CalDAV Radicale

Un servidor del Protocolo de Contexto de Modelo (MCP) construido con FastMCP / el SDK oficial de MCP para Python que conecta agentes LLM (como Nous Hermes, Claude, OpenAI) con un calendario y administrador de tareas CalDAV autoalojado Radicale.

Características

📅 Eventos de calendario (VEVENT)

• get_events: Consulta eventos dentro de rangos de fecha/hora con búsqueda opcional por palabra clave en resumen, descripción y ubicación.

• get_free_busy_slots: Calcula espacios de tiempo abiertos y no reservados dentro de horarios laborales configurables (p. ej. 9:00 a. m. - 5:00 p. m.) en cualquier zona horaria IANA.

• create_event: Programa nuevos eventos con validación automática ISO, invitaciones a asistentes y detección de solapamientos/conflictos.

• update_event: Modifica eventos existentes por UID sin sobrescribir los campos no tocados.

• delete_event: Elimina eventos por UID.

📝 Tareas y pendientes (VTODO)

• list_todos: Obtiene tareas pendientes o completadas filtradas por estado (NEEDS-ACTION, COMPLETED, IN-PROCESS, CANCELLED, ALL).

• create_todo: Crea tareas con fecha de vencimiento, niveles de prioridad (1-9) y descripciones.

• complete_todo: Marca tareas como completadas con marcas de tiempo automáticas de finalización.

🚀 Transportes e implementación

• Transporte STDIO: Transporte predeterminado para ejecución local (p. ej. Claude Desktop, agentes locales).

• Transporte SSE (Server-Sent Events): A través de HTTP para implementaciones remotas siempre activas (p. ej. Coolify, Docker).

Related MCP server: caldav-mcp

Configuración

Configura el servidor mediante variables de entorno o un archivo .env:

Inicio rápido local

1. Instalación

# 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. Configurar el entorno

Copia .env.example a .env y establece tus credenciales:

cp .env.example .env

3. Ejecutar localmente

Modo STDIO (canal local)

python server.py --stdio

Modo SSE (servidor HTTP)

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

4. Ejecutar el cliente de prueba

# 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. Ejecutar las pruebas automatizadas

pytest -v

Implementación en Coolify

Implementa el servidor MCP en Coolify sin configuración adicional:

1. Crea un nuevo servicio en Coolify: Docker Compose o Dockerfile.

2. Apunta al repositorio o pega el docker-compose.yml.

3. Establece las siguientes variables de entorno en la interfaz de Coolify:

   • 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. Expón el puerto 8000 mediante el proxy inverso de Coolify con tu dominio (p. ej. https://mcp-calendar.yourdomain.com).

5. Tu endpoint SSE será accesible en:

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

Integración con agentes LLM (Nous Hermes / Claude Desktop)

Configuración de Claude Desktop

Añade lo siguiente a tu claude_desktop_config.json:

STDIO local:

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

SSE remoto (Coolify):

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

Integración con el agente Nous Hermes

Las definiciones de herramientas se generan automáticamente a partir de los docstrings con especificaciones de tipo. Ejemplo de uso de prompt:

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

Licencia

MIT