calendar-mcp

Local MCP server that exposes Apple Calendar data through an EventKit helper app.

Built entirely by OpenAI GPT-5.4 via Codex.

Install

git clone https://github.com/<your-account>/calendar-mcp.git
cd calendar-mcp
./bootstrap.sh

Related MCP server: calendar-app-mcp

Run

npm run start

Permissions

Run calendar_permissions once with prompt: true and access: "full".

The helper app is intended to be built with the project’s normal code signing so macOS can attribute Calendar access to a stable app identity.

If the prompt does not appear from inside Codex, launch the helper app directly once:

open CalendarMCPHelperApp/build/Build/Products/Release/CalendarMCPHelperApp.app

When opened directly, the app will request Calendar access and show a status alert. After that initial grant, the MCP tools can read and write events normally.

Delete safety is intentionally narrow: each calendar_delete_event call can remove only one resolved target. Recurring deletes support one occurrence or one entire series, but not futureEvents or any bulk-delete shape.

calendar_update_event updates an event in place instead of forcing a delete-and-recreate flow. Omitted fields stay unchanged. To clear nullable fields, pass one of clearLocation, clearNotes, clearUrl, or clearTimeZone.

Date Inputs

All tool date inputs accept these wire formats:

• 2026-04-02 for a local calendar day

• 2026-04-02T09:30 or 2026-04-02T09:30:00 for a local wall-clock time

• 2026-04-02T09:30:00-05:00 or 2026-04-02T14:30:00Z for an exact instant

Local date-only and local date-time inputs are interpreted in the helper app's current macOS time zone. Returned event payloads always use ISO-8601 timestamps with timezone offsets.

calendar_list_events treats start and end as the exact time window after parsing those inputs.

occurrenceDate for recurring-event lookups also accepts YYYY-MM-DD. In that case the helper matches the occurrence by local calendar day. When you already have an occurrenceDate timestamp from a previous tool response, prefer passing that exact timestamp back.

MCP config

{
  "mcpServers": {
    "calendar": {
      "command": "node",
      "args": ["/absolute/path/to/calendar-mcp/dist/index.js"],
      "env": {
        "CALENDAR_MCP_HELPER_APP_PATH": "/absolute/path/to/calendar-mcp/CalendarMCPHelperApp/build/Build/Products/Release/CalendarMCPHelperApp.app"
      }
    }
  }
}

Verify

npm run verify