{ "markdown": "# mcp-calendar\n\n\n\n**MCP server for reading ics calendars, free busy time and scheduling conflicts.** Read .ics calendars: events, free and busy, conflicts, exports.\n\nWorks with Claude Desktop, Claude Code, Cursor and any Model Context Protocol client. Runs on your own machine, or hosted with no install.\n\n## Install\n\n**Hosted, nothing to install.** Get a token from (the connect page) or (the same token as JSON); a free anonymous one is issued on the spot and a Pro key works the same way. Then point an MCP client at `https://mcp.zovo.one/mcp/calendar` over streamable-http and send the token as `Authorization: Bearer `.\n\nIf your client cannot set headers, put the token in the path instead: `https://mcp.zovo.one/mcp/calendar/t/`. Both forms work. The bare URL with no token answers 401 on `tools/call`, so the token is not optional.\n\n**Claude Desktop, one click.** Download `calendar.mcpb` from the [latest release](https://github.com/theluckystrike/mcp-servers/releases/latest) and double-click it.\n\n**From source.** The mirror is self-contained: every `@theluckystrike/*` dependency is vendored, so a fresh clone builds with no extra setup.\n\n```sh\ngit clone https://github.com/theluckystrike/mcp-calendar.git\ncd mcp-calendar\nnpm install && npm run build\n```\n\nThen point your client at the built entry point:\n\n```json\n{\n \"mcpServers\": {\n \"calendar\": {\n \"command\": \"node\",\n \"args\": [\"/absolute/path/to/mcp-calendar/dist/index.js\"]\n }\n }\n}\n```\n\n> `@theluckystrike/mcp-calendar` is **not published on npm yet**, so an `npx -y @theluckystrike/mcp-calendar` command will fail. The three paths above are the working ones and each is exercised by CI.\n\n![calendar demo](https://raw.githubusercontent.com/theluckystrike/mcp-servers/main/assets/demo-calendar.gif)\n\nRead-only mirror of [mcp-servers/servers/calendar](https://github.com/theluckystrike/mcp-servers/tree/main/servers/calendar). See [MIRROR.md](MIRROR.md).\n\n\n\nYour calendar app can show you next Tuesday. It cannot tell you where your week actually went, which two things you\nsaid yes to at the same time, or how many billable hours last month's meetings were worth. This server reads the\n`.ics` file your calendar already exports and answers those questions: events in any window with recurring series\nexpanded properly, merged busy blocks and the real free gaps inside your working hours, every double booking across\nwork and personal calendars at once, a clean `.ics` of just the events you picked, and the exact time entry for a\nmeeting you should have billed. No account is connected, nothing is synced, and the calendar file stays on your\nmachine as plain text.\n\nBuilt by [theluckystrike](https://github.com/theluckystrike).\n\n\n**Import the .ics your calendar exports, then ask what is on, when you are free, and what clashes -- zero setup, all local.**\n\n## 60-second install\n\nnpm publish for `@theluckystrike/mcp-calendar` is pending. Until then, the `.mcpb` one-click bundle or a clone+build\nis the working path -- both are verified below.\n\n**One-click (.mcpb):** download `calendar.mcpb` from the latest release and double-click it in Claude Desktop:\nhttps://github.com/theluckystrike/mcp-servers/releases/latest\n\n**Claude Desktop** (`claude_desktop_config.json`):\n\n```json\n{\n \"mcpServers\": {\n \"calendar\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@theluckystrike/mcp-calendar\"]\n }\n }\n}\n```\n\n**Claude Code:**\n\n```sh\nclaude mcp add calendar -- npx -y @theluckystrike/mcp-calendar\n```\n\n**Cursor** (`.cursor/mcp.json`):\n\n```json\n{\n \"mcpServers\": {\n \"calendar\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@theluckystrike/mcp-calendar\"]\n }\n }\n}\n```\n\nThe `npx` form above starts working the moment the package is published. Until then, use the .mcpb bundle above,\nor build from source with exactly these four commands:\n\n```sh\ngit clone https://github.com/theluckystrike/mcp-servers.git && cd mcp-servers\nnpm install\nnpm run build -w packages/mcp-license -w servers/timezone -w servers/calendar\n```\n\nThen point your client's `command` at `node` with one arg: the absolute path to `servers/calendar/dist/index.js`.\n\nTo run in Pro mode set `MCP_LICENSE_KEY` in the same config block, or call `license_activate` once with your key.\n\n## Getting the .ics out of your calendar\n\n| App | Where |\n| --- | --- |\n| Google Calendar | Settings -> Import & export -> Export. You get a zip; import the `.ics` inside it. |\n| Apple Calendar | File -> Export -> Export... |\n| Outlook (desktop) | File -> Save Calendar, format iCalendar (.ics) |\n| Outlook / Microsoft 365 (web) | Settings -> Calendar -> Shared calendars -> Publish, then use the ICS link (Pro) |\n| Anything else | Any published feed URL ending in `.ics`, or `webcal://` (Pro) |\n\nThen: `ics_import {path: \"~/Downloads/mike@example.com.ics\", name: \"work\"}`\n\n## Tools\n\n| Tool | What it does |\n| --- | --- |\n| `ics_import` | Read a `.ics` file (`path`), pasted contents (`text`) or a public feed (`url`, Pro) and keep it locally under a name. Importing the same name again replaces it. |\n| `calendars_list` | Every imported calendar: name, source, event count, size, when it was imported. |\n| `events_list` | Every event between two dates with recurring series expanded to real occurrences, sorted, in your own time zone. Each row carries an id. |\n| `events_search` | Events whose title, description, location, organizer or attendees contain a phrase. |\n| `free_busy` | Merged busy blocks and the free gaps inside your working hours, day by day. Events marked free/transparent do not count as busy. |\n| `conflicts` | Every pair of events that overlap, with the overlap in minutes -- across all calendars, so a client call clashing with a school run is caught. A longer window is shortened to the free 31 days and answered, never refused. |\n| `next_event` | The next thing that has not started, and how long until it does. |\n| `event_export` | Write chosen events (by id, or a whole window) to a new `.ics` you can send. Times in UTC, so it lands correctly in any client. |\n| `event_to_time_entry` | Turn one meeting into the exact arguments for the time-tracker's `entry_add`, so a call becomes billable time without retyping it. |\n| `ics_forget` | Remove one calendar and its local copy. |\n| `license_status` / `license_activate` | Show the tier; activate a Pro key offline. |\n\nResource `calendar://today` gives today's schedule in one read. Prompt `plan_my_day` walks the whole loop: what is on,\nwhat clashes, where the free stretches are, and which finished meetings to bill.\n\n### What the parser handles\n\nWritten against real exports, not just the spec: line folding (CRLF, bare LF and bare CR, and folds that Exchange\nplaces inside a multi-byte character, which are rejoined on the bytes before decoding), `\\n \\, \\; \\\\` escaping,\nwhole-day events with an exclusive `DTEND`, `DURATION` instead of `DTEND`, `TZID` and UTC times, floating times,\n`RRULE` for `HOURLY`, `DAILY`, `WEEKLY`, `MONTHLY` and `YEARLY` with `COUNT`, `UNTIL` (inclusive), `INTERVAL`,\n`BYDAY` including ordinals (`2MO`, `-1FR`), `BYMONTHDAY`, `BYMONTH` and `BYSETPOS`, `EXDATE`, `RDATE`,\n`RECURRENCE-ID` overrides (the moved instance replaces the original instead of appearing twice),\n`STATUS:CANCELLED`, `TRANSP:TRANSPARENT`, and `VALARM` blocks inside an event. An event it cannot read is skipped\nand counted rather than costing you the rest of the file.\n\n`FREQ=MINUTELY` and `FREQ=SECONDLY` are deliberately not expanded: one such rule fills any window with thousands of\noccurrences and buries the rest of the week. Those events are listed at their first occurrence and the reason is\nsaid out loud. A rule with no `COUNT` and no `UNTIL` is expanded only as far as the window you asked for.\n\nExports written by this server keep whole-day events as `DATE` values, so a holiday leaves as the same day it\narrived rather than a timed block on the day before in your machine's zone.\n\n`VTIMEZONE` is deliberately ignored. A file's inline DST rules are only as fresh as the app that wrote it; the `TZID`\nis kept and every offset is computed from the ICU data inside your Node build instead, which is what keeps a weekly\nWarsaw 10:00 meeting at 10:00 local across the March clock change.\n\n## Free vs Pro\n\n| | Free | Pro ($19 one-time) |\n| --- | --- | --- |\n| Calendars kept | 2 | unlimited |\n| Window per question | up to 31 days | any window |\n| `conflicts` over a longer window | answered for the first 31 days, cap named | any window |\n| Events per export | 50 | unlimited |\n| Import from a URL or webcal feed | -- | yes |\n| Everything else | full | full |\n\n[Get Pro](https://mcp.zovo.one/buy/calendar) -- or $39 for every server in the suite, lifetime.\n\n## Privacy\n\nEverything is local. The calendar file you import is copied to\n`${XDG_DATA_HOME:-~/.local/share}/mcp-servers/calendar/` and read from there; deleting that directory resets the\nserver. There is exactly one network call in the whole server, and only when you pass a `url` yourself: it fetches\nthat address once, with a 12-second timeout, a 5 MB cap, and a refusal on loopback, private and cloud-metadata\naddresses. Nothing is uploaded, no account is linked, and licence keys verify offline.\n\n## Pairs with\n\n- [mcp-timezone](../timezone/README.md) -- this server reads its time zone and `.ics` engine from it: convert a meeting time, find slots across countries, write an invite.\n- [mcp-time-tracker](../time-tracker/README.md) -- `event_to_time_entry` hands it a finished meeting; it tracks and reports the hours.\n- [mcp-invoice](../invoice/README.md) -- turn those tracked hours into a numbered invoice.\n- [office-suite](../office-suite/README.md) -- several servers behind one install, one config entry.\n\n## FAQ\n\n**Does it connect to my Google or Outlook account?**\nNo. There is no OAuth, no token and no sync. You export a file (or paste a public feed URL on Pro) and it is read\nlocally. That also means an import is a snapshot: re-import when the calendar has moved on.\n\n**Do recurring events work properly?**\nYes, and that is most of the code. A weekly series is expanded on the wall clock, so a Warsaw 10:00 meeting stays\n10:00 through the DST change rather than drifting to 11:00. Monthly on the 31st skips February instead of rolling into\nMarch, `UNTIL` includes the occurrence that falls exactly on it, and a single moved instance replaces the original.\n\n**Why is my whole-day event one day shorter than I expected?**\nIt is not: RFC 5545 makes `DTEND` exclusive for a whole-day event, so 1--3 June means the 1st and the 2nd. This\nserver follows the spec, which is what your calendar app does too.\n\n**Can it write to my calendar?**\nIt writes `.ics` files with `event_export`, which you can import anywhere. It never modifies the calendar it read.\n\n**How big a file can it read?**\n5 MB, which is a few thousand events. Export a narrower date range if a full history is bigger than that.\n", "bytes": 11009, "sha": "885b415592ca1bc90ed0fddc0d6ed222eb5e6c280b0529d1ff2ef6c9480fcaa8", "repo_slug": "theluckystrike/mcp-calendar", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/plg_theluckystrike_mcp_calendar_e60d93c1/readme" }