renfield-mcp-calendar

Unified MCP server for calendar access — connect Exchange (EWS), Google Calendar, and CalDAV (Nextcloud, ownCloud, Radicale) through a single Model Context Protocol interface.

Features

• Multi-calendar — Configure multiple calendar accounts via YAML, query them individually or all at once

• Cross-calendar merge — list_events without a calendar parameter returns events from ALL calendars sorted chronologically

• Three backends — Exchange Web Services (EWS), Google Calendar API, CalDAV

• No passwords in config — Credentials referenced via environment variable names

• Lazy connections — Backend clients are initialized on first use, not at startup

• Async-ready — All blocking I/O wrapped with asyncio.run_in_executor

• Google OAuth2 helper — Built-in --auth google CLI for initial token setup

Related MCP server: Apple Calendar MCP Server

Installation

pip install renfield-mcp-calendar

Or directly from GitHub:

pip install "renfield-mcp-calendar @ https://github.com/ebongard/renfield-mcp-calendar/archive/refs/heads/main.tar.gz"

Configuration

Set CALENDAR_CONFIG to point to your YAML config file (default: /config/calendar_accounts.yaml).

Example calendar_accounts.yaml

calendars:
  # Exchange 2019 (on-premise, direct EWS endpoint)
  - name: work
    label: "Work Calendar"
    type: ews
    ews_url: "https://exchange.example.com/EWS/Exchange.asmx"
    username_env: CALENDAR_WORK_USERNAME
    password_env: CALENDAR_WORK_PASSWORD

  # Google Calendar (OAuth2 Desktop Flow)
  - name: family
    label: "Family Calendar"
    type: google
    calendar_id: "primary"
    credentials_file: "/config/google_calendar_credentials.json"
    token_file: "/data/google_calendar_token.json"

  # Nextcloud / CalDAV
  - name: club
    label: "Club Calendar"
    type: caldav
    url: "https://nextcloud.example.com/remote.php/dav/calendars/user/club/"
    username_env: CALENDAR_CLUB_USERNAME
    password_env: CALENDAR_CLUB_PASSWORD

Security: Passwords and tokens are never stored in the YAML file — use *_env fields to reference environment variable names.

Backend-specific notes

Google Calendar setup (one-time)

1. Google Cloud Console → Create project → Enable Google Calendar API

2. Create OAuth2 credentials (Desktop App) → Download credentials.json

3. Place as google_calendar_credentials.json in your config directory

4. Run the auth flow:

   python -m renfield_mcp_calendar --auth google --calendar family

5. Complete the browser-based authorization — token is saved automatically

MCP Tools

Example queries (via LLM)

• "Was steht heute an?" → list_events() (all calendars, today)

• "Was steht im Firmenkalender diese Woche?" → list_events(calendar="work", start="...", end="...")

• "Erstelle einen Familientermin morgen um 14 Uhr: Zahnarzt" → create_event(calendar="family", ...)

• "Bin ich morgen Nachmittag frei?" → list_events(start="...", end="...")

Usage

# Run as MCP server (stdio transport)
python -m renfield_mcp_calendar

# Or via entry point
renfield-mcp-calendar

# Google OAuth2 setup (one-time)
python -m renfield_mcp_calendar --auth google --calendar family

Claude Desktop / MCP client config

{
  "mcpServers": {
    "calendar": {
      "command": "python",
      "args": ["-m", "renfield_mcp_calendar"],
      "env": {
        "CALENDAR_CONFIG": "/path/to/calendar_accounts.yaml",
        "CALENDAR_WORK_USERNAME": "user@example.com",
        "CALENDAR_WORK_PASSWORD": "secret"
      }
    }
  }
}

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests (29 tests)
pytest tests/ -v

License

MIT