Apple Calendar Mcp

Apple Calendar MCP Server

[](https://github.com/s-morgan-jeffries/apple-calendar-mcp/actions/workflows/test.yml) [](https://github.com/s-morgan-jeffries/apple-calendar-mcp) [](https://www.python.org) [](LICENSE)

A comprehensive, fast, reliable, and agent-friendly MCP server for Apple Calendar on macOS.

Why This Server

Comprehensive

10 tools covering the full calendar lifecycle — more than any other dedicated Apple Calendar MCP server. Full CRUD for events and calendars, plus batch operations (create_events, update_events), text search, smart availability with working hours and minimum duration filters, and conflict detection. Complete recurring event support with iCalendar RRULE — create, update, and delete individual occurrences or entire series.

Fast

All event operations use Swift/EventKit via native subprocess for sub-second performance, even on calendars with thousands of events. Calendar management uses AppleScript where it's fast enough.

| Operation | Typical Time | Notes | |-----------|-------------|-------| | List calendars | 0.5s | 16 calendars | | Read events (1 month) | 0.6s | ~100 events | | Read events (1 year) | 0.7s | ~1,400 events | | Create event | 0.5s | | | Update event | 0.6s | | | Delete events (batch of 5) | 0.4s | Single commit |

Reliable

97% code coverage from 184 unit tests. 59 integration tests run against real Calendar.app — covering round-trip data integrity, recurring event edge cases, special characters, alerts, year-boundary queries, and more. Calendar safety guards prevent accidental writes to real calendars during testing.

Agent-Friendly

Every tool docstring includes detailed Returns sections documenting fields, types, and chaining info — so Claude knows that create_events returns UIDs usable by update_events without guessing. 38 blind agent eval scenarios validate tool usability across multiple models.

| Model | Score | Safety | |-------|-------|--------| | Claude Sonnet 4 | 76/76 (100%) | 5/5 | | DeepSeek V3 | 71/76 (93%) | 5/5 | | Mistral Large 2411 | 70/76 (92%) | 5/5 | | Qwen 2.5 72B | 69/76 (91%) | 5/5 | | Llama 3.3 70B | 63/76 (83%) | 5/5 |

All models pass all safety-critical scenarios. [Full results](evals/agenttoolusability/results/scored_results.md).

Tools (10)

Calendars

| Tool | Description | |------|-------------| | get_calendars | List all calendars with names, access levels, descriptions, and colors | | create_calendar | Create a new calendar | | delete_calendar | Delete a calendar and all its events |

Events

| Tool | Description | |------|-------------| | get_events | Query events in a date range | | search_events | Search events by text across one or all calendars | | create_events | Create one or more events in one operation | | update_events | Update one or more events by UID, with full recurrence support | | delete_events | Delete one or more events by UID |

Scheduling

| Tool | Description | |------|-------------| | get_availability | Find free time slots across calendars, with optional working hours and minimum duration filters | | get_conflicts | Detect double-bookings and overlapping events across calendars |

Prerequisites

• macOS (Apple Calendar is macOS-only)
• Python 3.10+
• Xcode Command Line Tools — required for Swift helper compilation (xcode-select --install)

Installation

# With uv (recommended)
uv tool install apple-calendar-mcp

# With pip
pip install apple-calendar-mcp

Configuration

Claude Desktop

Add to your Claude Desktop MCP config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "apple-calendar": {
      "command": "uvx",
      "args": ["apple-calendar-mcp"]
    }
  }
}

Or if running from a local clone:

{
  "mcpServers": {
    "apple-calendar": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/apple-calendar-mcp", "python", "-m", "apple_calendar_mcp.server_fastmcp"]
    }
  }
}

Other MCP Clients

Run the server directly:

apple-calendar-mcp

Or from source:

uv run python -m apple_calendar_mcp.server_fastmcp

Permissions

On first use, macOS will prompt for calendar access permission. Grant access to allow the server to read and write calendar events. The Swift helpers use EventKit, which requires the "Full Disk Access" or "Calendars" permission depending on your macOS version.

Development

make install           # Create venv and install dependencies
make test              # Run all tests (176 unit, 58 integration)
make test-unit         # Unit tests only
make test-integration  # Integration tests (requires test calendar)
make complexity        # Check cyclomatic complexity
make audit             # Check dependencies for vulnerabilities

All dates use ISO 8601 format in local time: "2026-03-15" for date-only or "2026-03-15T14:30:00" for date-time. Do not append "Z" — dates are not UTC.

Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

License

[MIT](LICENSE)

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: s-morgan-jeffries
• Source: s-morgan-jeffries/apple-calendar-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.