cal-provider

What it is

cal-provider is a Python library that abstracts away the differences between Google Calendar and CalDAV-compatible services (like iCloud, Nextcloud, and Fastmail). It provides a single asynchronous API for listing calendars, checking availability, retrieving events, and creating or canceling meetings. It includes built-in error handling, timezone support, and an optional Model Context Protocol (MCP) server to allow AI agents to interact with calendars, along with a web-based admin UI for easy configuration.

Features

• Unified async API for Google Calendar and CalDAV (iCloud, Nextcloud, Fastmail)
• Automatic timezone conversion for event retrieval and availability checks
• Optional MCP server for seamless integration with AI agents
• Web-based admin UI for credential setup and connection testing
• Structured exception hierarchy for granular error handling
• Support for listing calendars, checking slots, and creating/canceling events

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] -->|Async Calls| Provider[Calendar Provider Interface]
    Provider -->|Implements| Google[Google Calendar Backend]
    Provider -->|Implements| CalDAV[CalDAV Backend]
    Google -->|OAuth/Service Account| GAPI[Google Calendar API]
    CalDAV -->|HTTP Basic/Digest| CServer[CalDAV Server]
    AdminUI[Admin UI] -->|Generates Config| Env[.env File]
    MCPServer[MCP Server] -->|Uses| Provider
    User -->|Optional| MCPServer

How it's built

The library is built in Python using an async-first design. It implements a provider pattern where specific backend implementations (Google, CalDAV) adhere to a common interface. It uses standard Python libraries for datetime handling and likely HTTP clients for API communication. The project includes an optional admin UI built with a web framework (likely serving on port 8100) and an MCP server component for AI integration. Configuration is managed via environment variables or generated .env files.

How it runs

sequenceDiagram
    participant App as User Application
    participant Lib as cal-provider
    participant Backend as Calendar Backend
    App->>Lib: get_provider("google", creds)
    Lib-->>App: Provider Instance
    App->>Lib: get_available_slots(cal_id, start, end)
    Lib->>Backend: Fetch Events
    Backend-->>Lib: Raw Event Data
    Lib->>Lib: Calculate Free Slots
    Lib-->>App: List[TimeSlot]
    App->>Lib: create_event(cal_id, event)
    Lib->>Backend: Create Event
    Backend-->>Lib: Event ID/Status
    Lib-->>App: Result Dict

How to apply & reuse

Use cal-provider when building Python applications that need to interact with multiple calendar backends without maintaining separate code paths for each. It is ideal for scheduling bots, AI agents requiring calendar access via MCP, or internal tools that need to check availability and book meetings across different organizational calendar systems. Install it via pip with the appropriate extras for your target backend.

At a glance