mcp-apple-calendar

A lightweight MCP server for Apple Calendar on macOS. Uses a compiled Swift helper (cal-helper) that talks directly to the system's EventKit framework -- no AppleScript, no Calendar.app dependency, no timeout issues with Exchange/iCloud accounts.

Works with any MCP client: Claude Desktop, OpenCode, Cursor, Zed, or anything else that supports the MCP stdio transport.

Requirements

• macOS 13+
• Node.js 18+
• Swift (for building cal-helper -- included with Xcode or xcode-select --install)
• Calendar access granted to cal-helper in System Settings > Privacy & Security > Calendars

Install

git clone https://github.com/barrettclark/mcp-apple-calendar
cd mcp-apple-calendar
npm install
swiftc -O -o cal-helper cal-helper.swift

Then run cal-helper once from Terminal to trigger the macOS Calendar access prompt:

./cal-helper list-calendars

Grant access in the system dialog (or in System Settings > Privacy & Security > Calendars). Restart any app (VS Code, Claude Desktop, etc.) that will host the MCP server after granting access.

Configure your MCP client

Add this to your MCP client config (e.g. ~/.config/opencode/opencode.json or Claude Desktop's claude_desktop_config.json):

{
  "mcp": {
    "apple-calendar": {
      "type": "local",
      "command": ["node", "/absolute/path/to/mcp-apple-calendar/index.js"]
    }
  }
}

Tools

Tool	Description
check_calendar_access	Verify EventKit can access Calendar. Run this if other tools fail.
list_calendars	List all calendars grouped by account (iCloud, Exchange, Google, etc.) with selection state.
get_config	Show configured default calendars and source labels.
set_calendars	Choose which calendars to query by default (full list, or add/remove).
set_calendar_source	Add a custom label to a calendar (e.g. "Work" → "iCloud").
get_today	Return today's events sorted by start time.
get_events	Return events for a date range (YYYY-MM-DD).

First-time setup

1. Run list_calendars -- calendars are grouped by account automatically (iCloud, Exchange, Google, etc.).
2. Run set_calendars with the names you want as defaults:

set_calendars(["Calendar", "Barrett"])

Your selection is saved to ~/.config/mcp-apple-calendar/config.json.

Troubleshooting

Calendar access denied error

Run ./cal-helper list-calendars from Terminal to trigger the macOS permission prompt. Grant access, then restart any app hosting the MCP server.

Events missing

Make sure the relevant calendar is checked in Calendar.app's sidebar (unchecking a calendar unloads its data from the local store). Also confirm the calendar name is in your configured defaults (get_config).

cal-helper not found

Compile it first: swiftc -O -o cal-helper cal-helper.swift from the project directory.

Files

File	Purpose
index.js	MCP server entry point, tool definitions and handlers
calendar.js	EventKit helpers via cal-helper subprocess
cal-helper.swift	Swift CLI using EventKit -- compile to cal-helper binary
cal-helper	Compiled binary (not committed -- build locally)
config.js	Config read/write to ~/.config/mcp-apple-calendar/config.json
test.js	Smoke test -- run with node test.js

License

MIT

A lightweight MCP server for Apple Calendar on macOS. Reads events from Calendar.app using osascript -- no extra permissions, no cloud APIs, no heavy dependencies.

Works with any MCP client: Claude Desktop, OpenCode, Cursor, Zed, or anything else that supports the MCP stdio transport.

Requirements

• macOS (tested on macOS 14+)
• Node.js 18+
• Calendar.app configured with your accounts

Install

git clone https://github.com/barrettclark/mcp-apple-calendar
cd mcp-apple-calendar
npm install

Configure your MCP client

Add this to your MCP client config (e.g. ~/.config/opencode/config.json or Claude Desktop's claude_desktop_config.json):

{
  "mcp": {
    "apple-calendar": {
      "type": "local",
      "command": "node",
      "args": ["/absolute/path/to/mcp-apple-calendar/index.js"]
    }
  }
}

Tools

Tool	Description
check_calendar_access	Verify Calendar.app is reachable and accounts are authenticated. Run this if other tools time out.
list_calendars	List all calendar names. Shows which ones are currently selected as defaults.
get_config	Show your currently configured default calendars.
set_calendars	Choose which calendars to query by default. Pass [] to reset.
get_today	Return today's events, sorted by start time.
get_events	Return events for a date range (YYYY-MM-DD).

First-time setup

1. Run list_calendars to see all available calendars.
2. Run set_calendars with the names you want:

set_calendars(["Calendar", "Work"])

Your selection is saved to ~/.config/mcp-apple-calendar/config.json. After that, get_today and get_events will use those calendars automatically.

To query a different calendar for a single call, pass calendars as an argument -- it overrides the default for that call only.

To reset to querying all calendars, run set_calendars([]).

Troubleshooting

Events not showing up / timeouts

Calendar.app may need to re-authenticate an account (common with Exchange accounts after a token rotation). Run check_calendar_access -- if it reports an error, open Calendar.app, go to Settings > Accounts, and re-authenticate the affected account.

Some calendars are slow

Exchange and iCloud calendars can take several seconds to respond. Configure set_calendars to include only the calendars you actually use -- this eliminates unnecessary queries to slow accounts.

Calendar source / account not shown

Apple Calendar's AppleScript API doesn't expose which account (iCloud, Exchange, Google) a calendar belongs to. If you have multiple calendars with the same name (e.g. three Birthdays calendars -- one per account), they're indistinguishable in list_calendars. A future enhancement would use a Swift/EventKit helper to expose account info; for now, use trial and error with get_today to figure out which same-named calendar holds the events you care about.

AppleScript can return stale recurring event instances for events outside the requested date range. This server filters them out in JavaScript after the AppleScript query. If you see events from the wrong date, file an issue.

Files

File	Purpose
index.js	MCP server entry point, tool definitions and handlers
calendar.js	osascript helpers (checkAccess, listCalendars, getEvents, getEventsMulti)
config.js	Config read/write to ~/.config/mcp-apple-calendar/config.json
test.js	Smoke test -- run with node test.js

License

MIT