{
  "markdown": "# apple-calendar-mcp\n\nAn [MCP](https://modelcontextprotocol.io) server that lets an AI assistant\nread and create events in Apple Calendar — and work out when you actually\nhave time.\n\n**macOS only.** It talks to EventKit, Apple's own calendar framework, which\nhas no cross-platform equivalent.\n\n```bash\nclaude mcp add apple-calendar -- npx -y @redpop/apple-calendar-mcp\n```\n\nNo Xcode, no Swift toolchain, no repository clone. The signed helper binary\nships inside the package.\n\n## What it does\n\nMost calendar integrations answer *what is on my calendar*. This one also\nanswers **when am I free**:\n\n```\n\"Find me two hours for deep work this week, outside meetings\"\n\"When could I fit a 30-minute call with someone in Berlin?\"\n\"Book focus time Thursday morning\"\n```\n\n`find_free_time` returns the open gaps, not the busy blocks. It understands\nthat \"work\" means weekdays during working hours, that \"personal\" means any\nday, and that all-day events usually shouldn't count as busy.\n\nIt can also keep a buffer around each meeting, because a gap wedged directly\nbetween two calls is free on paper and useless in practice.\n\nAlongside that, the usual: list calendars, read events in a range with\noptional text search, create, update and delete events with location, notes,\nalarms, all-day or timed. Recurring events come back as individual\noccurrences, not as the master event — a detail AppleScript-based servers\nroutinely get wrong.\n\nChanging or deleting an occurrence of a recurring event requires saying\nexplicitly whether you mean just that one or every later one too. There is\nno default for that, because \"cancel this Tuesday\" and \"never again\" are not\nthe kind of thing to guess at.\n\nFull parameter reference: [`docs/tools.md`](./docs/tools.md).\n\n## Requirements\n\n- macOS 14 (Sonoma) or newer\n- Node.js 20 or newer\n\nNothing else. Building from source additionally needs Xcode Command Line\nTools, but installing from npm does not.\n\n## Setup\n\n**1. Add the server to your client.**\n\n<details open>\n<summary><strong>Claude Code</strong></summary>\n\n```bash\nclaude mcp add apple-calendar -- npx -y @redpop/apple-calendar-mcp\n```\n\n</details>\n\n<details>\n<summary><strong>Claude Desktop</strong></summary>\n\nQuit Claude Desktop first (Cmd+Q) — it rewrites its config on exit, so\nediting while it runs discards your change. Then add to\n`~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"apple-calendar\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@redpop/apple-calendar-mcp\"]\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><strong>Cursor, Windsurf, Zed and other MCP clients</strong></summary>\n\nAny client that speaks MCP over stdio works. The command is `npx`, the\narguments are `-y @redpop/apple-calendar-mcp`, and no environment variables\nare needed.\n\n</details>\n\n**2. Grant calendar access on first use.**\n\nAsk your assistant *\"what calendars do I have?\"*. A system dialog appears\nasking to let **calendar-helper** — not your assistant, the helper itself —\naccess your calendar.\n\nConfirm it, then open **System Settings → Privacy & Security → Calendars →\ncalendar-helper → Options…** and make sure **Full Access** is selected, not\n\"Add Only\". Read-only access is not enough; the helper checks for full access\nat startup.\n\nThis one dialog is the only manual step, and no package format can take it\naway. It appears once and survives updates.\n\n## Why the dialog says \"calendar-helper\"\n\nmacOS grants calendar permission to the *responsible parent process*, not to\nthe program actually asking. An AI client that declares no calendar usage in\nits bundle therefore locks out everything it starts — silently, with no\ndialog and no entry in System Settings. Several MCP calendar servers work\naround this by telling you to launch your client from a terminal.\n\nThis one doesn't need that. The helper disclaims that inherited\nresponsibility at startup and becomes its own permission identity, so macOS\nreads the usage description from *its* bundle and prompts under its own name.\nOne grant then covers every client on the machine.\n\nThe full story: [`docs/architecture.md`](./docs/architecture.md).\n\n## Updating\n\n```bash\nnpx -y @redpop/apple-calendar-mcp@latest\n```\n\nYour calendar grant survives updates: the helper is installed to a fixed\npath, and macOS binds the grant to that path rather than to the binary's\ncontents.\n\n## Uninstalling\n\nRemove the `apple-calendar` entry from your client's MCP configuration and\nrestart it. Then delete the helper and its permission:\n\n```bash\nrm -rf ~/Library/Application\\ Support/apple-calendar-mcp\n```\n\nThe entry under **System Settings → Privacy & Security → Calendars** stays\nbehind — macOS keeps those even when the binary is gone. Switch it off there\nif you want it revoked.\n\n## Building from source\n\n```bash\ngit clone https://github.com/redpop/apple-calendar-mcp.git\ncd apple-calendar-mcp\nnpm install && npm run build && ./swift/build.sh\n```\n\nThen point your client at `dist/index.js` with `node` instead of using `npx`.\nWithout a Developer ID certificate the helper is signed ad-hoc, and macOS\nthen ties the calendar grant to the exact build — expect a new permission\ndialog after every rebuild.\n\n## Learn more\n\n- [`docs/architecture.md`](./docs/architecture.md) — how the two halves fit\n  together and the whole TCC permission story\n- [`docs/tools.md`](./docs/tools.md) — every tool parameter, defaults, and\n  the all-day alarm rule\n- [`docs/cli.md`](./docs/cli.md) — the standalone `calendar-helper` command,\n  useful for testing without an MCP client\n- [`docs/troubleshooting.md`](./docs/troubleshooting.md) — common errors and\n  how to fix them\n\n## Privacy\n\nEverything runs locally. Calendar data goes from EventKit to the helper to\nthe MCP server to your client, and nowhere else. There is no network code in\nthis project.\n\n## License\n\nMIT — see [`LICENSE`](./LICENSE).\n",
  "bytes": 5855,
  "sha": "f460d8a3d37c0f723736d58d0eddd33fe6456033d28da588bf94b717133c7cfc",
  "repo_slug": "redpop/apple-calendar-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_redpop_apple_calendar_mcp_6e68209d/readme"
}