ical-mcp

MCP server for Apple Calendar and CalDAV providers.

Works with iCloud, Fastmail, Nextcloud, and any CalDAV-compatible calendar. No macOS dependency — runs headless on any platform.

Quick start

# Install
uvx ical-mcp

# Or from source
uv sync
uv run ical-mcp

Configuration

Set these environment variables (or copy .env.example to .env):

iCloud setup

1. Go to account.apple.com → Sign-In and Security → App-Specific Passwords

2. Generate a new password (label it "ical-mcp")

3. Set ICAL_MCP_URL=https://caldav.icloud.com

4. Set ICAL_MCP_USERNAME to your Apple ID email

5. Set ICAL_MCP_PASSWORD to the generated app-specific password

Tools

Write protection

All calendars are read-only by default. You must explicitly opt in to writes:

# Single calendar (by name or ID)
ICAL_MCP_WRITABLE_CALENDARS=home

# Multiple calendars
ICAL_MCP_WRITABLE_CALENDARS=home,Work

# All calendars (use with caution)
ICAL_MCP_WRITABLE_CALENDARS=*

# Not set or empty — all calendars are read-only

list_calendars shows "access": "read-only" or "access": "read-write" for each calendar, so the AI agent knows what it can and can't modify.

Using calendar IDs (UUIDs) instead of names avoids issues with spaces and renames.

Transport

# Local use with Claude Code / Claude Desktop (default)
ical-mcp

# Shared HTTP server for multi-agent access
ical-mcp --transport http --port 8093

# Bind to a specific address (e.g. Tailscale IP)
ical-mcp --transport http --host 100.64.0.1 --port 8093

Claude Code configuration

Local (stdio)

{
  "mcpServers": {
    "ical-mcp": {
      "command": "uvx",
      "args": ["ical-mcp"],
      "env": {
        "ICAL_MCP_URL": "https://caldav.icloud.com",
        "ICAL_MCP_USERNAME": "your@icloud.com",
        "ICAL_MCP_PASSWORD": "xxxx-xxxx-xxxx-xxxx",
        "ICAL_MCP_WRITABLE_CALENDARS": "your-calendar-id"
      }
    }
  }
}

Remote (HTTP)

{
  "mcpServers": {
    "ical-mcp": {
      "url": "http://your-server:8093/mcp"
    }
  }
}

Safety features

• Per-calendar write protection — read-only by default, explicit opt-in per calendar

• Backup before mutate — every update/delete logs the full iCal data to stderr

• ETag concurrency — updates fail if the event was modified elsewhere since last fetch

• Semantic errors — clear messages for auth failures, rate limits, conflicts, and read-only violations

License

MIT