Cal Provider

What it is

A Python library that abstracts calendar operations behind a single async interface, supporting Google Calendar (via service accounts) and CalDAV providers (iCloud, Nextcloud, Fastmail). It includes an administrative web UI for credential setup and configuration generation, and an optional Model Context Protocol (MCP) server to expose calendar capabilities to AI agents.

Features

• Unified async API for Google Calendar and CalDAV (iCloud, Nextcloud, Fastmail)
• Admin UI wizard for credential setup, connection testing, and config generation
• Optional MCP server for AI agent integration
• Timezone-aware availability checking and event retrieval
• Structured exception hierarchy for granular error handling
• Round-trip testing dashboard for create/cancel workflows

Quickstart

pip install -e ".[google]"
python -c "
import asyncio
from datetime import datetime, timezone
from cal_provider import get_provider

async def main():
    provider = get_provider('google', service_account_path='/path/to/sa.json')
    slots = await provider.get_available_slots(
        'primary',
        start=datetime(2026, 3, 15, 9, 0, tzinfo=timezone.utc),
        end=datetime(2026, 3, 15, 18, 0, tzinfo=timezone.utc),
        duration_minutes=30,
    )
    for slot in slots:
        print(f'{slot.start:%I:%M %p} - {slot.end:%I:%M %p}')

asyncio.run(main())
"

Architecture

flowchart TD
    User[User Application]
    AdminUI[Admin UI Web Server]
    MCPServer[MCP Server]
    CoreLib[Cal Provider Core]
    GoogleBackend[Google Calendar Backend]
    CalDAVBackend[CalDAV Backend]
    GoogleAPI[Google Calendar API]
    CalDAVServer[CalDAV Server]
    
    User --> CoreLib
    AdminUI --> CoreLib
    MCPServer --> CoreLib
    CoreLib --> GoogleBackend
    CoreLib --> CalDAVBackend
    GoogleBackend --> GoogleAPI
    CalDAVBackend --> CalDAVServer

How it's built

Python 3.12+ using asyncio for all I/O. It implements a provider pattern with specific backends for Google Calendar API and CalDAV. The admin UI is likely built with a lightweight web framework (implied by local host serving), and the MCP server integrates with the core provider logic to expose tools like get_available_slots and create_event.

How it runs

sequenceDiagram
    participant Client as Client Application
    participant Provider as Calendar Provider
    participant Backend as Specific Backend
    participant Remote as Remote Calendar Service
    
    Client->>Provider: get_available_slots calendar_id start end duration
    Provider->>Backend: fetch_events calendar_id start end
    Backend->>Remote: HTTP Request for Events
    Remote-->>Backend: Event List JSON/ICS
    Backend-->>Provider: Normalized Events
    Provider->>Provider: Calculate Free Slots
    Provider-->>Client: List of TimeSlots

How to apply & reuse

Use it in Python applications requiring calendar integration without locking into a single vendor. Ideal for booking bots, scheduling assistants, or AI agents needing to read/write events across different calendar ecosystems. The MCP server allows LLMs to interact with calendars naturally.

At a glance