Chronos MCP - Advanced CalDAV Management Server

A comprehensive Model Context Protocol (MCP) server for CalDAV calendar management, built with FastMCP 2.0. Chronos provides advanced calendar and event management capabilities with multi-account support.

🚀 Features

• Multi-account Support: Manage multiple CalDAV servers simultaneously

• Full CRUD Operations: Create, read, update, and delete calendars and events ✅

• Advanced Event Management:

  • Recurring events with RRULE support ✅

  • Event updates with partial field modifications ✅

  • Attendee management and invitations (JSON format) ✅

  • Reminders and alarms (VALARM) ✅

  • Timezone-aware operations

• Advanced Search:

  • Full-text search across events ✅

  • Field-specific search (title, description, location) ✅

  • Multiple match types (contains, starts_with, exact, regex) ✅

  • Date range filtering ✅

  • Relevance ranking algorithm ✅

• Bulk Operations:

  • Create multiple events in parallel ✅

  • Delete multiple events efficiently ✅

  • Atomic operations with rollback ✅

  • Configurable error handling modes ✅

• Security Hardening:

  • Comprehensive input validation ✅

  • XSS and injection prevention ✅

  • Path traversal protection ✅

  • RFC-compliant validation ✅

• Task Management: Full VTODO support ✅

• Journal Entries: Full VJOURNAL support ✅

📋 Task Management (VTODO)

Chronos MCP provides comprehensive support for CalDAV tasks:

• Create tasks with due dates, priorities, and descriptions

• Track progress with percentage completion (0-100%)

• Manage status: NEEDS-ACTION, IN-PROCESS, COMPLETED, CANCELLED

• Create subtasks using related_to relationships

• Bulk operations for efficient task management

Available tools:

• create_task — Create a task with summary, due date, priority, description

• list_tasks — List tasks in a calendar, optionally filtering by status

• update_task — Partial update of task fields (status, priority, progress, etc.)

• delete_task — Delete a task by UID

• bulk_create_tasks — Create multiple tasks in parallel

• bulk_delete_tasks — Delete multiple tasks in parallel

# Example: Create a task
mcp call create_task '{
  "calendar_uid": "my-calendar",
  "summary": "Complete project documentation",
  "due": "2025-02-01T15:00:00Z",
  "priority": 2
}'

📓 Journal Entries (VJOURNAL)

Keep detailed records with CalDAV journal entries:

• Create journal entries with timestamps and rich descriptions

• Link related entries using related_to relationships

• Organize with categories for better searchability

• Update and manage existing journal entries

Available tools:

• create_journal — Create a journal entry with summary and description

• list_journals — List journal entries in a calendar

• update_journal — Partial update of journal fields

• delete_journal — Delete a journal entry by UID

• bulk_create_journals — Create multiple journal entries in parallel

• bulk_delete_journals — Delete multiple journal entries in parallel

# Example: Create a journal entry
mcp call create_journal '{
  "calendar_uid": "my-calendar",
  "summary": "Team Meeting Notes",
  "description": "Discussed Q1 objectives..."
}'

For detailed usage, see VTODO/VJOURNAL Guide.

🔐 Security

Secure Password Storage (New!)

Chronos MCP now supports secure password storage using your system's keyring (via python-keyring). When available, passwords are automatically stored in:

• macOS: Keychain Access

• Windows: Windows Credential Locker

• Linux: Secret Service (GNOME Keyring, KWallet, etc.)

Migration to Secure Storage

If you have existing accounts with passwords stored in plain text, migrate them to secure storage:

# Check what will be migrated (dry run)
python scripts/migrate_to_keyring.py --dry-run

# Perform actual migration
python scripts/migrate_to_keyring.py

The migration script will:

1. Read existing passwords from ~/.chronos/accounts.json

2. Store them securely in your system keyring

3. Create a backup of the original configuration

4. Remove passwords from the JSON file

Fallback Behavior

If keyring is not available (e.g., SSH sessions, containers), Chronos MCP will:

• Warn about the security implications

• Fall back to storing passwords in the configuration file

• Automatically attempt to migrate passwords to keyring when it becomes available

Legacy Security Warning

Note: If keyring is not installed or available, passwords will be stored in plain text at ~/.chronos/accounts.json. Install keyring support with:

pip install "chronos-mcp[secure]"  # or just: pip install keyring

Installation

Standard Installation

pip install -e .

Secure Installation (Recommended)

Includes keyring support for secure password storage:

pip install -e ".[secure]"

Or if you already have Chronos installed:

pip install keyring>=24.0.0

Configuration

Environment Variables (Default Account)

CALDAV_BASE_URL=http://<YOUR_CALDAV_SERVER>:5232
CALDAV_USERNAME=<YOUR_USERNAME>
CALDAV_PASSWORD=<YOUR_PASSWORD>

Multi-Account Configuration

Create ~/.chronos/accounts.json:

{
  "accounts": {
    "personal": {
      "url": "http://<YOUR_CALDAV_SERVER>:5232",
      "username": "<YOUR_USERNAME>",
      "display_name": "Personal Calendar"
    },
    "work": {
      "url": "https://caldav.company.com",
      "username": "user",
      "display_name": "Work Calendar"
    }
  },
  "default_account": "personal"
}

Note: Passwords are not included in the JSON when using keyring. They will be:

• Prompted for on first use and stored securely

• Migrated from existing configuration using scripts/migrate_to_keyring.py

• Only stored in JSON if keyring is unavailable (with a warning)

Usage

Running the Server

./run_chronos.sh

Basic Operations

List all configured accounts:

list_accounts()

Example Tool Usage

Create an event with reminder:

chronos:create_event(
    calendar_uid="assistant",
    summary="Team Meeting",
    start="2025-07-08T14:00:00",
    end="2025-07-08T15:00:00",
    location="Conference Room",
    alarm_minutes="15"  # Note: Pass as string!
)

Create recurring event with attendees:

chronos:create_event(
    calendar_uid="work",
    summary="Weekly Standup",
    start="2025-07-07T09:00:00",
    end="2025-07-07T09:30:00",
    recurrence_rule="FREQ=WEEKLY;BYDAY=MO,WE,FR",
    attendees_json='[{"email": "team@example.com", "name": "Team"}]'
)

Delete an event:

chronos:delete_event(
    calendar_uid="assistant",
    event_uid="abc-123-def-456"
)

Update an event (partial update):

chronos:update_event(
    calendar_uid="assistant",
    event_uid="abc-123-def-456",
    location="Room 202",  # Update location
    alarm_minutes="30"    # Change reminder to 30 minutes
    # Other fields remain unchanged
)

Documentation

• Usage - Basic tool usage examples

• Architecture Guide - System design and components

• RRULE Guide - Recurring events documentation

• VTODO/VJOURNAL Guide - Task and journal management

• Architecture Decisions - ADR records

• Contributing - Development guidelines

• Security Policy - Security reporting and practices

Known Issues

See GitHub Issues for current limitations and workarounds.

Changelog

See CHANGELOG.md for version history.

Contributing

See CONTRIBUTING.md for development guidelines.