@mgcrea/mcp-apple-calendar 0.0.0-bootstrap

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Olivier Louvignes <olivier@mgcrea.io>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,72 @@
+# @mgcrea/mcp-apple-calendar
+
+Model Context Protocol server for the macOS **Apple Calendar** app.
+
+> **Unofficial.** Not affiliated with Apple. It reads the Calendar store already on your Mac.
+
+## One lane for reads, one for writes
+
+- **Index lane** — read-only SQLite over `Calendar.sqlitedb`. Every read goes through it.
+- **Apple Events lane** — writes only. There is no `jxa/read.ts` in this package, and a test asserts
+  there never will be.
+
+**This is the inverse of Notes.** Notes shipped on Apple Events because search took 97 ms. Calendar
+cannot: a ±90-day range query over 1,349 events takes **3,355 ms** over Apple Events, `whose` is
+worse and unstable, and every per-property bulk fetch costs ~1.8 s whichever property it is — so the
+cost cannot be amortised the way Notes amortises a bulk fetch. The store opens read-only in **1 ms**.
+Calendar needs the file lane for speed, not capability.
+
+It does **not** need EventKit, which is why the companion app stays a pure broker rather than
+linking a framework that would drag its own TCC prompt in.
+
+| Permission                | Needed for  | Without it                                |
+| ------------------------- | ----------- | ----------------------------------------- |
+| **Full Disk Access**      | all reads   | nothing works — there is no read fallback |
+| **Automation → Calendar** | writes only | reads are unaffected                      |
+
+Neither is granted to Calendar.app — it is the _reader_ that needs permission. Grant Full Disk
+Access to whatever launches the server (Terminal, iTerm, VS Code, Claude), then restart it.
+
+With writes off — the default — **no Automation prompt appears at all**. A read-only Calendar server
+needs exactly one permission.
+
+## Tools
+
+Read: `diagnostics`, `list_accounts`, `list_calendars`, `list_events`, `search_events`, `get_event`.
+
+Write, registered **only** when `APPLE_CALENDAR_ALLOW_WRITES=1` — with the flag off they are
+invisible to the model, not merely refused: `create_event`, `update_event`, `delete_events`.
+
+## Configuration
+
+| Variable                                        | Default    |                                               |
+| ----------------------------------------------- | ---------- | --------------------------------------------- |
+| `APPLE_CALENDAR_ALLOW_WRITES`                   | off        | Register the mutating tools.                  |
+| `APPLE_CALENDAR_ACCOUNTS`                       | all        | Read-side allowlist, comma-separated.         |
+| `APPLE_CALENDAR_CALENDARS`                      | all        | Read-side allowlist, comma-separated.         |
+| `APPLE_CALENDAR_DEFAULT_CALENDAR`               | Calendar's | Calendar a new event goes to when none named. |
+| `APPLE_CALENDAR_DEFAULT_RANGE_DAYS`             | `7`        | An unbounded default would scan a decade.     |
+| `APPLE_CALENDAR_MAX_RANGE_DAYS`                 | `366`      | Ceiling on a caller-supplied range.           |
+| `APPLE_CALENDAR_DEFAULT_EVENT_DURATION_MINUTES` | `60`       | Used when a write names no end.               |
+| `APPLE_CALENDAR_INCLUDE_DECLINED`               | off        | Include declined events in reads.             |
+| `APPLE_CALENDAR_INCLUDE_CANCELLED`              | off        | Include cancelled events in reads.            |
+| `APPLE_CALENDAR_TIMEZONE`                       | system     | Override the zone ranges are resolved in.     |
+| `APPLE_CALENDAR_INDEX_MODE`                     | `auto`     | `auto` \| `ro` \| `immutable` \| `off`.       |
+| `APPLE_CALENDAR_STORE`                          | auto       | Explicit `Calendar.sqlitedb` path.            |
+| `APPLE_CALENDAR_OSASCRIPT_TIMEOUT_MS`           | `30000`    | Sized for the first-run permission prompt.    |
+
+## Notes that will bite you
+
+- **`~/Library/Calendars` does not exist.** The store is
+  `~/Library/Group Containers/group.com.apple.calendar/Calendar.sqlitedb`.
+- **Recurrence lives in a cache table.** A naive `SELECT ... FROM CalendarItem` over a date range
+  misses expanded repeats; the range query unions items carrying no recurrence rule with everything
+  in the cache. 456 of 489 cached parents carry no rule of their own.
+- **Dates are seconds since 2001**, not 1970 — `CalendarItem.last_modified` and `orig_date` both.
+- **A floating time zone is not the system one.** Anything matching `GMT±HHMM` is a real zone;
+  treating the rest as floating is what stops a two-hour silent shift.
+- **Writes always go through Apple Events**, never the store, which the app holds open and syncs.
+
+## Licence
+
+[MIT](LICENSE).

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/cli.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import { A as BUILD_INFO, C as CALENDAR_SURFACE, a as loadConfig, r as createServer } from "./server-B2HtiXLF.js";
+import { runStdioServer } from "@mgcrea/mcp-apple-core";
+//#region src/cli.ts
+const LOG_PREFIX = "apple-calendar-mcp";
+runStdioServer({
+	build: BUILD_INFO,
+	surface: CALENDAR_SURFACE,
+	logPrefix: LOG_PREFIX,
+	start: async (logger) => {
+		const config = loadConfig();
+		const { server } = createServer({
+			config,
+			logger
+		});
+		return {
+			server,
+			banner: `writes=${config.allowWrites ? "ENABLED" : "disabled"}, calendars=${config.calendars.length ? config.calendars.join("/") : "all"}, range=${config.defaultRangeDays}d, index=${config.indexMode}`
+		};
+	}
+}).catch((err) => {
+	console.error(`[${LOG_PREFIX}] fatal:`, err);
+	process.exit(1);
+});
+//#endregion
+export {};
+
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","names":[],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { runStdioServer } from \"@mgcrea/mcp-apple-core\";\n\nimport { BUILD_INFO } from \"./build-info.js\";\nimport { CALENDAR_SURFACE } from \"./client/errors.js\";\nimport { loadConfig } from \"./config.js\";\nimport { createServer } from \"./server.js\";\n\nconst LOG_PREFIX = \"apple-calendar-mcp\";\n\nrunStdioServer({\n  build: BUILD_INFO,\n  surface: CALENDAR_SURFACE,\n  logPrefix: LOG_PREFIX,\n  start: async (logger) => {\n    const config = loadConfig();\n    const { server } = createServer({ config, logger });\n    return {\n      server,\n      banner:\n        `writes=${config.allowWrites ? \"ENABLED\" : \"disabled\"}, ` +\n        `calendars=${config.calendars.length ? config.calendars.join(\"/\") : \"all\"}, ` +\n        `range=${config.defaultRangeDays}d, ` +\n        `index=${config.indexMode}`,\n    };\n  },\n}).catch((err: unknown) => {\n  console.error(`[${LOG_PREFIX}] fatal:`, err);\n  process.exit(1);\n});\n"],"mappings":";;;;AAQA,MAAM,aAAa;AAEnB,eAAe;CACb,OAAO;CACP,SAAS;CACT,WAAW;CACX,OAAO,OAAO,WAAW;EACvB,MAAM,SAAS,WAAW;EAC1B,MAAM,EAAE,WAAW,aAAa;GAAE;GAAQ;EAAO,CAAC;EAClD,OAAO;GACL;GACA,QACE,UAAU,OAAO,cAAc,YAAY,WAAW,cACzC,OAAO,UAAU,SAAS,OAAO,UAAU,KAAK,GAAG,IAAI,MAAM,UACjE,OAAO,iBAAiB,WACxB,OAAO;EACpB;CACF;AACF,CAAC,CAAC,CAAC,OAAO,QAAiB;CACzB,QAAQ,MAAM,IAAI,WAAW,WAAW,GAAG;CAC3C,QAAQ,KAAK,CAAC;AAChB,CAAC"}