Apple Calendar

Apple Calendar

MCP server for Apple Calendar on macOS.

Provides access to calendars and events through EventKit. Keep Calendar as the system of record while enabling agents to read, create, update, and delete events.

When to use

• Calendar-only workflows
• EventKit-backed calendar access without the all-in-one server
• Tighter app-level separation for scheduling

What It Does

• Discover and list calendars
• Create, read, update, and delete events
• Tool discovery helpers search_tools and get_tool_info for context-constrained clients
• Today resources and planning prompts
• Health checks that distinguish empty results from blocked access
• Read fallback through Calendar.app automation when native EventKit reads are blocked on supported local setups
• Permission recovery: calendar_permission_guide, calendar_recheck_permissions

Install On This Mac

uvx apple-calendar-mcp

git clone https://github.com/JonathanRReed/Apple-MCPs.gitcd Apple-MCPsuv sync --all-packages

Install In AI Agents

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

claude mcp add --transport stdio --scope user apple-calendar -- uvx apple-calendar-mcp

Selecting calendar and event identifiers

Call calendar_list_calendars, select the intended calendar by its displayed name and source, and pass its returned calendar_id unchanged to calendar_list_events, calendar_create_event or the destination of calendar_update_event. Native EventKit listings return native identifiers; automation listings use calendar names as identifiers. When EventKit can read calendars, a calendar name passed to calendar_create_event or calendar_update_event is resolved to its native calendar, ignoring case and extra whitespace, so the write keeps full alarm support. A name shared by several calendars returns AMBIGUOUS_CALENDAR with the candidates; pass the intended calendar_id instead. Unknown names return CALENDAR_NOT_FOUND and read-only calendars return CALENDAR_READ_ONLY. Without native calendar read access, names still use automation.

After changing Calendar permissions, restart the MCP server and call calendar_list_calendars again to refresh identifiers. For full alarm replacement or clearing, list events with the native calendar_id and pass the returned native event_id to calendar_update_event. Existing applescript:: event IDs still use automation after permissions change. Treat event IDs as opaque: re-list to obtain native IDs instead of rewriting an existing token. Calendar writability, safety modes and allowlists still apply.

Bridge Batch Lookup

The internal Python CalendarBridge.get_events(event_ids) method batches native lookups without adding an MCP tool. Pass a sequence of non-empty strings, at most 10000 input IDs. Duplicate input IDs are resolved once. Requests are chunked to an exact 32768-byte UTF-8 JSON argv budget, including JSON escaping; an individual oversized ID is rejected before any lookup.

The returned mapping distinguishes:

• An event value: a validated response for the requested ID
• None: an explicit native miss confirmed through the existing single-get/JXA fallback, or a definitive miss on that fallback path
• An absent key: unknown, including unanswered, malformed, contradictory, duplicate-response, mismatched, or unsupported entries

JXA-issued IDs are opaque versioned tokens that identify the Automation backend, calendar scope, and exact UID or id() namespace/value. Do not parse or construct them. UID-less events keep their actual typed id() value; distinct events with identical metadata no longer collapse. Rows without usable identifiers, or duplicate provider identities, receive display-only weak tokens. Weak tokens cannot prove absence or authorize writes.

Versioned tokens resolve directly through verified, server-filtered JXA lookups. A single matching calendar and event are required; ambiguous, unavailable, malformed, or mismatched lookups remain unknown. No unfiltered event-directory scan is used. Lookup snapshots are capped at 1000 calendars and 1000 returned matches per query, and identifiers at 32768 characters. Legacy bare UID/id values still resolve when their namespaces unambiguously identify the same event. Legacy calendar/start/title composites remain readable when unique, but cannot authorize mutations or definitive batch absence. Legacy values that resemble versioned tokens are rejected if their meanings conflict.

Legacy fallback identifiers, including encoded identifiers that could also be literal provider UIDs, require collision checks across calendars. Those exact queries can exceed the 30-second fallback deadline on large calendar stores. A timeout is an explicit error and does not establish absence or permit a mutation. Full native EventKit access avoids that fallback lookup for native identifiers: grant the host app full Calendar access, list events again to obtain native IDs, then retry. Existing fallback identifiers retain their strict collision checks.

Native misses retry the single-get/JXA path. If the whole native batch cannot answer, a fallback miss for an opaque native ID remains unknown because JXA may use a different identifier format. A verified versioned JXA miss can establish absence. Permission or per-ID confirmation failures remain unknown; non-fallback whole-helper transport failures remain explicit errors. A valid native reply with a different canonical ID requires a separate single-get lookup confirming that canonical ID. Conflicting or unconfirmed aliases remain unknown. Unsupported legacy uid: IDs remain unknown without a lookup. Callers must not delete mappings for absent keys.

JXA in-place updates and deletion require a strong, unique identity and reject stale calendar names before writing. Calendar moves through the JXA fallback are explicitly unsupported because cloning cannot safely preserve every event field. Native Calendar moves remain available. Recurrence updates through versioned JXA IDs are also unsupported.

The native batch command itself reports EventKit-only lookup outcomes. Synthetic IDs produce UNSUPPORTED_IDENTIFIER; native EVENT_NOT_FOUND alone is not a confirmed absence across both backends.

Safety Modes

• safe_readonly
• safe_manage
• full_access

Calendar allowlists

Set these environment variables in your MCP client's configuration, then restart the server:

For an assistant that may read your schedule but only write to a dedicated calendar:

{  "APPLE_CALENDAR_MCP_SAFETY_MODE": "safe_manage",  "APPLE_CALENDAR_MCP_WRITE_ALLOWED_CALENDARS": "AI Planning"}

Leaving either allowlist unset or empty applies no restriction from that list. When both are set, writes must pass both; safe_readonly blocks all writes regardless of either list. Moving an event checks both the source and destination calendar. A write with an unresolved target is rejected when an allowlist is configured.

Names are exact, case-sensitive matches after trimming configuration whitespace. Every calendar with a matching name is included, so use unique calendar names for security-sensitive scopes. calendar_health reports the configured write allowlist.

These are policies enforced by the Python MCP server, not a macOS sandbox. Direct use of the native helper or bridge library does not enforce them. macOS permissions still apply, and your MCP client may send returned data to its model provider.

Transport

stdio is the default and recommended transport. Set APPLE_CALENDAR_MCP_TRANSPORT=streamable-http (with optional APPLE_CALENDAR_MCP_HOST and APPLE_CALENDAR_MCP_PORT) to serve Streamable HTTP instead.

macOS Permissions

• Calendar access is required
• calendar_health reports native access_status, read access, and write access without trying AppleScript fallback or requesting permissions. Explicit Calendar reads can still use the existing automation fallback.

Launch Checklist

• Add uvx apple-calendar-mcp (or a clone's Apple-Calendar-MCP/start.sh) to your MCP client
• Reload or reconnect the client so the Calendar tool surface is loaded into context
• Call calendar_health first
• If access is blocked or access_status is not_determined, call calendar_permission_guide
• After changing macOS permissions, call calendar_recheck_permissions

Prompting Notes

• tools/list returns the full Calendar tool surface. Context-constrained clients can use search_tools first, then get_tool_info for the Calendar tool they need.
• Before creating events, confirm the date, time, duration, and title with the user
• Use Calendar for scheduled time blocks, meetings, and appointments

Related

• Apple-Tools-MCP

Event alerts

calendar_create_event and calendar_update_event accept alarms: an array of { "minutes_before": 15 } or { "absolute_iso": "2030-10-11T10:00:00Z" } objects. Absolute dates require an explicit Z or UTC offset; timezone-naive dates are rejected. Relative offsets must be whole minutes from 0 through 525600; each event accepts at most 100 alarms. Omit alarms to preserve existing alerts on update, or pass [] to clear them.

Event detail and list responses include alarm metadata. EventKit reports relative, absolute, and location alerts. Full alarm replacement and clearing require native EventKit access. The Calendar scripting fallback can create initial display alerts and read the alert types exposed by Calendar's scripting dictionary. If an alarm edit requires removing existing alerts, or the existing alert collections cannot be read, it returns ALARM_EDIT_REQUIRES_NATIVE before changing any event fields. Omit alarms to preserve existing alerts while updating other fields. Fallback updates that combine explicit alarms (including []) with any non-null title, time, location, notes or all-day field require native EventKit, even if that field already has the supplied value. An unchanged calendar_id is not a field write; moves remain unsupported. Alarm-only updates can add initial display alerts when all four alert collections are readable and empty; [] is then a no-op. Fallible event-record reads finish before insertion. If an insertion fails or a mutation times out, the outcome may be unknown: no individual alerts are deleted, and the event must be inspected before retrying. Fallback parity is still tracked in issue #41.

calendar_health reports alarm_edit_backend: "native_eventkit" and can_edit_existing_alarms, based on native read/write permission. Calendar writability and server safety rules still apply to each edit.

Thanks to LightSpeedSpirit for the original event-alarm contribution in PR #26.

Repeating events

Every occurrence of a repeating event shares one event_id, so calendar_update_event and calendar_delete_event take two optional arguments that say which occurrences a write covers. calendar_list_events marks these events with recurring: true.

• scope: "occurrence" for one occurrence, "following" for that occurrence and every later one, or "series" for every occurrence.
• occurrence_start_iso: for "occurrence" and "following", the occurrence's start exactly as calendar_list_events returned it.

A write to a repeating event without scope changes nothing. If the client supports MCP forms (elicitation) and the call names an occurrence, the server asks the user to choose: only this occurrence, this and all following, or the whole series. Otherwise it returns RECURRING_EVENT_SCOPE_REQUIRED, telling the agent to ask the user and call again. The user, not the model, makes the choice, so an agent can't delete a whole series by guessing. A user who declines the question gets CANCELLED_BY_USER. Events that don't repeat work exactly as before.

An occurrence edited on its own gets its own event_id; writes through it accept the same scope. With "series", a new start_iso/end_iso moves every occurrence by the same amount. deleted in the response reports whether the targeted occurrences are actually gone. Scopes need native EventKit access; Calendar automation returns UNSUPPORTED_OPERATION.

Thanks to vlasovpe-sg for the detailed report and root-cause analysis in issue #79.