# 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

```bash
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:

```bash
./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`):

```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

```bash
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`):

```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