Icskit

Let your AI work with the .ics calendar files on your own disk: agenda, search, free time, conflicts and safe edits. No account, no OAuth, no network.

icskit-mcp is an MCP server for local iCalendar files: the .ics export from Google Calendar, Apple Calendar or Outlook, or a folder of them.

What is different about it. Other .ics MCP servers lean on a calendar library or only read published feeds. This one ships its own RFC 5545 parser and recurrence engine, and the part that is usually wrong in calendar tools is the part that is tested hardest:

• Daylight saving is exact. A 09:00 Berlin meeting stays at 09:00 Berlin across the clock change; a time that falls in the spring-forward gap or the fall-back overlap is resolved the way RFC 5545 says; DTEND lengths are real elapsed time; free-time search keeps your wall-clock working hours on 23 and 25 hour days. Tested against America/New_York, Europe/Berlin and Europe/Istanbul (which has no DST), for IANA zones and for custom VTIMEZONE blocks such as Outlook's W. Europe Standard Time.
• Recurrence is checked against the spec. 30 worked examples from RFC 5545 section 3.8.5.3 (the ones that use supported parts) are test cases, and about a thousand randomized rules are compared against python-dateutil as an independent oracle.
• Writes are safe by construction. Editing works by line surgery: everything you did not ask to change (other events, VTIMEZONE, VALARM, unknown X- properties, folding, line endings, a BOM) stays byte for byte. By default the original is never touched; you get an edited copy or a patch.
• Local only. Nothing is sent anywhere. Attendee email addresses are just text in the file.
• Several calendars at once: free time and conflicts work across all of them.

It is free and MIT licensed, with no paid tier.

Install

You need uv. Pick the folder that holds your .ics files; the server can see only that folder (searched recursively).

Claude Code

claude mcp add icskit -- uvx icskit-mcp --dir "/path/to/calendars"

Claude Desktop - add this to claude_desktop_config.json (Settings, Developer, Edit config):

{
  "mcpServers": {
    "icskit": {
      "command": "uvx",
      "args": ["icskit-mcp", "--dir", "C:\\Users\\you\\Calendars"]
    }
  }
}

(--dir can also be given as the ICSKIT_MCP_DIR environment variable.)

Getting your calendars out

• Google: Settings, Import & export, Export. You get a zip of one .ics per calendar.
• Apple Calendar: File, Export, Export...
• Outlook: File, Save Calendar (or "Export" in the new Outlook), choose iCalendar format.

Try asking

• "What does my week of 2026-03-02 look like? Use Europe/Istanbul."
• "When am I free for 90 minutes next Tuesday and Wednesday, between 10:00 and 16:00, with 15 minutes of buffer around meetings?"
• "Do any of my calendars have meetings that overlap this month?"
• "What are the next 6 times my 'Board sync' happens?"
• "Find every event with [email protected] that is not cancelled."
• "Add a dentist appointment on 2026-03-10 at 15:00 for 45 minutes (Europe/Istanbul). Show me the patch first."
• "Cancel just the 2026-03-11 occurrence of the Monday/Wednesday/Friday standup."
• "Write my week as Markdown notes."

Tools

Tool	What it does
calendar_overview	Files, calendar names, event and recurring-series counts, date span, time zones used, and every problem found (files that failed to load, events skipped and why). Call first.
agenda	Every occurrence in a window, sorted and grouped by day, recurring events expanded (RRULE, EXDATE, RDATE, modified instances), recurrence marked.
search_events	Text, attendee, location or regex search; lists events/series, or expanded occurrences when you give a window.
find_free_time	Free blocks of at least N minutes inside working hours and working days, across one or several calendars, with buffers.
find_conflicts	Overlapping events, including across calendars. All-day and "free" (TRANSPARENT) events are ignored unless you ask.
next_occurrences	The next N occurrences of one event by UID.
export_agenda_markdown	A seven day agenda as Markdown, optionally saved to a new .md file.
create_event / update_event / delete_event	Safe writes (below). delete_event can remove a single occurrence of a recurring event (adds an EXDATE).

Time zones. Every tool takes tz (an IANA name such as Europe/Istanbul; default UTC) and every time in every answer is printed with its zone, never silently local. Floating times (no zone in the file) are read in the tz you pass. All-day events are dates and are not shifted by tz. A date-only end such as 2026-03-08 includes that whole day.

Safe writing

create_event, update_event and delete_event never modify your calendar unless you say so:

You pass	What happens
nothing	The edited calendar is written next to the original as <file>.new. The original is untouched. An existing .new file is never overwritten.
dry_run=true	Nothing is written; you get the patch (a unified diff).
output_file="x.ics"	The edited copy goes to that new file (it must not exist).
in_place=true	The original is replaced atomically (and refused if the file changed on disk since it was read).

Every result shows the patch. Edited files are parsed again before they are written, and a create-then-delete round trip is tested to reproduce the original file byte for byte. update_event bumps SEQUENCE and refreshes DTSTAMP; new events get a generated UID.

Limits (read these)

• Recurrence supports DAILY, WEEKLY, MONTHLY, YEARLY with INTERVAL, COUNT, UNTIL, BYDAY (with ordinals like 2MO, -1FR), BYMONTHDAY, BYMONTH, BYSETPOS, WKST, plus EXDATE, RDATE and RECURRENCE-ID overrides. HOURLY and finer, BYWEEKNO, BYYEARDAY and BYHOUR-style parts are rejected with a message (the event is skipped and listed under problems), never silently mis-expanded.
• DTSTART is always treated as the first instance, as RFC 5545 defines it, even if the rule would not generate it.
• RECURRENCE-ID;RANGE=THISANDFUTURE is reported and applied to one instance only.
• Only VEVENT is read (not VTODO/VJOURNAL). Updates change the whole series; editing a single instance is not supported (delete one occurrence is).
• New events reference an IANA TZID without embedding a VTIMEZONE; Google and Apple accept that, some Outlook versions may not.
• A TZID that is neither an IANA name nor defined by a VTIMEZONE in the same file (for example a bare Windows name without its definition) skips that event with an explanation.
• Files must be UTF-8. Attendee changes are recorded in the file only; no invitation is sent.

Security

• The server reads and writes only .ics files under --dir. Paths that escape it (.., absolute paths elsewhere, symlinks pointing outside) are refused.
• It makes no network connections and needs no credentials.
• Text you pass to write tools is escaped; newlines cannot inject extra properties, and control characters are refused.
• The only file other than .ics it can create is the Markdown export, and only as a new file.
• Calendar contents (titles, descriptions) come from your files and may contain text written by other people. Treat them as data, not instructions.

Development

uv sync --extra test
uv run pytest
uv run ruff check src tests && uv run mypy --strict src

A companion tutorial that builds a minimal version from scratch is in icskit-mcp-the-hard-way.

MIT licensed.