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.