eventkit-rs

A Rust library and CLI for interacting with macOS Calendar events and Reminders via Apple's EventKit framework. Includes a built-in Model Context Protocol (MCP) server for AI assistant integration.

Features

• Calendar Events — full CRUD with alarms, recurrence (incl. monthsOfTheYear / setPositions), attendees, location chip, URL, structured location, availability (Busy/Free/Tentative/Unavailable), calendar move, and EKSpan choice (this vs future) for recurring edits/deletes.
• Reminders — full CRUD with priority, alarms (time + geofence), recurrence (including monthsOfTheYear / setPositions etc.), due/start dates, due-date IANA timezone, and explicit completion-date setting.
• MCP Server — built-in MCP server (--mcp) with structured JSON output, typed input/output schemas, and 32 tools.
• Calendar Management — create, update (name + color), and delete both reminder lists and event calendars.
• Batch Operations — batch delete, move, and update across reminders and events.
• Authorization — programmatic consent prompts for Reminders, Calendar, and Location; status diagnostics with remediation hints.
• Location — get current location via CoreLocation; auto-prompt for location auth when a geofence is attached.
• In-Process Transport — embed as a library with serve_on() for DuplexStream-based in-process MCP.
• CLI + Dump + Reflection — command-line tool with curated JSON dumps and runtime ObjC reflection dumps (dump reminder-raw, dump reminder-private) for debugging.

iCloud caveats (verified empirically — see project notes). On iCloud-synced reminder lists, the iCloud daemon silently drops some EKReminder writes even when the framework call succeeds: the plain-text location, EKReminder.structuredLocation, EKAlarm.url/soundName/emailAddress. These setters exist in the lib (parity with EventKit) for non-iCloud sources, but the MCP/CLI surface for reminders is intentionally pruned of those fields. Calendar events are unaffected — their URL/location/etc. work end-to-end. For "remind me at a place" on iCloud, use a geofence (location-based alarm) — that's the iCloud-honored path.

Requirements

• macOS 14+ (Sonoma)
• Rust 1.94+

Installation

As a CLI Tool

cargo install eventkit-rs

As a Library

[dependencies]
eventkit-rs = "0.5"

Without MCP dependencies:

[dependencies]
eventkit-rs = { version = "0.5", default-features = false, features = ["events", "reminders"] }

Quick Start

Library Usage

use chrono::{Duration, Local};
use eventkit::{EventsManager, ReminderDraft, ReminderPatch, RemindersManager};

fn main() -> eventkit::Result<()> {
    // Reminders ----------------------------------------------------------
    let reminders = RemindersManager::new();
    reminders.request_access()?;

    let created = reminders.create_reminder(&ReminderDraft {
        title: "Buy groceries",
        notes: Some("Milk, eggs, bread"),
        priority: Some(1),
        due_date: Some(Local::now() + Duration::days(1)),
        due_date_timezone: Some("America/Los_Angeles"),
        ..Default::default()
    })?;
    println!("created: {}", created.identifier);

    // List incomplete items due before next week
    let upcoming = reminders.fetch_incomplete_reminders_in_due_range(
        None,
        Some(Local::now() + Duration::days(7)),
        None,
    )?;
    for r in upcoming {
        println!("- {}", r.title);
    }

    // Backdate completion
    reminders.update_reminder(
        &created.identifier,
        &ReminderPatch {
            completion_date: Some(Some(Local::now() - Duration::hours(2))),
            ..Default::default()
        },
    )?;

    // Calendar Events ----------------------------------------------------
    let events = EventsManager::new();
    events.request_access()?;
    for event in events.fetch_today_events()? {
        println!("{} at {}", event.title, event.start_date);
    }
    Ok(())
}

In-Process MCP (no separate binary)

use tokio::io::duplex;

let (client_stream, server_stream) = duplex(64 * 1024);

tokio::spawn(async move {
    eventkit::mcp::serve_on(server_stream).await.unwrap();
});

// Connect your MCP client to client_stream...

CLI Usage

# MCP server (stdio transport)
eventkit --mcp

# Authorization
eventkit status                              # reminders status
eventkit status --events                     # events status
eventkit reminders authorize                 # trigger consent dialog
eventkit events authorize

# Reminders — basics
eventkit reminders lists
eventkit reminders list --all
eventkit reminders add "Call mom" --notes "Birthday" --priority 1 --due-tz America/Los_Angeles
eventkit reminders show <id>
eventkit reminders update <id> --title "Call mom back" --priority 1
eventkit reminders update <id> --completion-date "2026-05-20 10:00"   # backdate complete
eventkit reminders update <id> --completion-date ""                   # mark incomplete
eventkit reminders complete <id>
eventkit reminders uncomplete <id>
eventkit reminders delete <id> --force

# Reminders — date-range queries (uses EventKit's native predicates)
eventkit reminders list --due-after 2026-05-25 --due-before 2026-06-01
eventkit reminders list --completed-after 2026-05-19 --completed-before 2026-05-21

# Reminders — posture setters
eventkit reminders set-due-tz <id> "America/Los_Angeles"
eventkit reminders set-geofence <id> --loc-title "Home" --lat 37.78 --lng -122.42 --radius 100 --proximity enter
eventkit reminders clear-geofence <id>
eventkit reminders set-URL <id> "https://example.com"   # diagnostic; iCloud may ignore in UI

# Calendar Events (URL + location are first-class on events)
eventkit events calendars
eventkit events list --today
eventkit events list --days 14 --all
eventkit events add "Meeting" --start "2026-03-22 14:00" --duration 60 \
    --url https://example.com/zoom --availability tentative
eventkit events add "Holiday" --start "2026-03-25" --all-day --location "Office"
eventkit events show <id>

# Calendar Events — update + recurring-event span semantics
eventkit events update <id> --location "Conf Room 4" --availability free
eventkit events update <id> --calendar "Work"                 # move calendars
eventkit events update <id> --all-day true                    # flip to all-day
eventkit events update <id> --title "Standup (moved)" --span future   # this + future
eventkit events update <id> --notes ""                        # clear notes
eventkit events delete <id> --force                           # delete this occurrence
eventkit events delete <id> --force --span future             # delete this + future

# Dump objects as JSON or raw ObjC reflection (debugging)
eventkit dump reminder-lists
eventkit dump calendars
eventkit dump sources
eventkit dump reminder <id>                  # curated JSON
eventkit dump reminders --list "Shopping"
eventkit dump reminder-raw <id>              # every @property on the EKReminder class chain
eventkit dump reminder-raw <id> --values     # ...with KVC value reads
eventkit dump reminder-private <id>          # probe non-public/private selectors
eventkit dump event <id>
eventkit dump events --days 30

MCP Server

All tools return structured JSON with typed output schemas. Responses use structured_content (MCP spec 2025-06-18) with text fallback for older clients.

Tools (32)

Prompts (4)

Configuration

Add to your MCP client config (e.g. Claude Desktop):

{
  "mcpServers": {
    "eventkit": {
      "command": "eventkit",
      "args": ["--mcp"]
    }
  }
}

Privacy Permissions

Embedded automatically when you use the CLI (see Info.plist in this repo). When linking as a library into your own app, add to your Info.plist:

<key>NSRemindersFullAccessUsageDescription</key>
<string>This app needs access to your reminders.</string>

<key>NSCalendarsFullAccessUsageDescription</key>
<string>This app needs access to your calendar.</string>

<key>NSLocationWhenInUseUsageDescription</key>
<string>This app needs your location for location-based reminders.</string>

<!-- Required for geofenced reminder triggers to fire when the app isn't foreground -->
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>This app needs background location access so location-based reminders trigger when you arrive at or leave a place.</string>

Feature Flags

Development

# Run all checks (format + clippy + build + nextest) — same as CI
./ci-check.sh

# Auto-fix formatting + clippy, then check
./ci-check.sh --fix

# Run tests directly (parallel via nextest; live-eventkit tests run serial)
cargo nextest run --all-features

# Run only the live-EventKit integration tests (touches real authorization)
cargo nextest run --all-features --run-ignored only

# Build universal binary (arm64 + x86_64)
./build-universal.sh

License

Apache 2.0 — see LICENSE.