Radicale CalDAV MCP Server

Сервер Model Context Protocol (MCP), созданный с помощью FastMCP / официального MCP Python SDK, который связывает LLM-агентов (таких как Nous Hermes, Claude, OpenAI) с самостоятельным Radicale CalDAV-календарём и менеджером задач.

Возможности

📅 События календаря (VEVENT)

• get_events: Запрос событий в диапазонах дат/времени с необязательным поиском по ключевым словам в заголовке, описании и местоположении.

• get_free_busy_slots: Поиск свободых временныых слот during настаиваемого рабачего времени (например, 9:00Am – 5:00PM) in any IANA time zone.

• create_event: Создание новые событий с автоматическим ISO-проверкой, приглашениями участников и обнаружением пересчений/конфликов.

• update_event: Изменение существующих событий по UID без перезаписи нетронутых полей.

• delete_event: Удаление событий по UID.

📝 Задачи и дела (VTODO)

• list_todos: Получение задач, ожидающих выполнения или завершённых, с фильтрацией по статусу (NEEDS-ACTION, COMPLETED, IN-PROCESS, CANCELLED, ALL).

• create_todo: Создание задач с датами выполнения, уровнями приоритета (1-9) и описаниями.

• complete_todo: Отметка задач как возвращаемых execution с автоматическим фиксированием времени завершения.

🚀 Транспорты и разverтывание

• STDIO транспорть: транспорть по молчанию в локального запуска (например, Claude Desktop, лоcalльные агенты).

• SSE (Server-Sent Events) транспорть: для удалённых постоянно работает положи (`например, оfriendly, DECHER).

Related MCP server: caldav-mcp

Конфигурация

Настройте сервер через переменные окружения или файл .env:

Быстрый старт локально

1. Установка

# 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. Настройка окружения

Скопируйте .env.example в .env и укажите свои учётные данные:

cp .env.example .env

3. Запуск локально

Режим STDIO (локальный конвейер)

python server.py --stdio

Режим SSE (HTTP-сервер)

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

4. Запуск тестового клиента

# 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. Запуск автоматизированных тестов

pytest -v

Развертывание на Coolify

Разверните MCP-сервер на Coolify без какой-либо настройки:

1. Создайте новый сервис в Coolify: Docker Compose или Dockerfile.

2. Укажите этот репозиторий или вставьте содержимое docker-compose.yml.

3. Установите следующие переменные окружения в интерфейсе 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. Откройте порт 8000 через обратный прокси Coolify с вашим доменом (например, https://mcp-calendar.yourdomain.com).

5. Ваш SSE-эндпоинт будет доступен по адресу:

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

Интеграция с LLM-агентами (Nous Hermes / Claude Desktop)

Конфигурация Claude Desktop

Добавьте следующее в ваш claude_desktop_config.json:

Локальный 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"
      }
    }
  }
}

Удалённый SSE (Coolify):

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

Интеграция агентов Nous Hermes

Определения инструментов автоматически генерируются из docstrings с указанием типов. Пример использования в промпте:

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

Лицензия

MIT