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

Related MCP server: Calendar MCP

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

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

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

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

License

MIT