---
name: ical
displayName: iCalendar Reader & Converter
description: Read, parse, and convert .ics iCalendar files to text, JSON, or
  CSV. Use when opening a calendar export, extracting events, or transforming
  schedule data.
tags:
  - calendar
  - ics
  - icalendar
  - converter
  - schedule
  - events
capabilities:
  - ReadIcal
  - ConvertToJson
  - ConvertToCsv
  - ExtractEvents
  - ListAttendees
  - MergeIcal
representativeQueries:
  - Read a .ics file and show me the events
  - Convert iCal to CSV
  - Extract all events from a calendar export
  - What attendees are in this .ics file?
  - Merge multiple .ics calendar files into one
version: 0.1.0
tier: curated
---

# iCalendar Reader & Converter

Reads `.ics` iCalendar files (RFC 5545) and converts them to human-readable text, JSON, or CSV — using only the Python standard library. Handles line-folding, backslash escaping, date/datetime parsing, and multi-component calendars.

## When to use

- Opening a `.ics` calendar export from Google Calendar, Apple Calendar, Outlook, or any CalDAV source.
- Extracting event data (title, time, location, attendees, description) for further processing.
- Converting a calendar file to CSV for spreadsheet import or to JSON for programmatic use.
- Auditing attendees or finding events in a date range within a calendar file.

## Steps

1. **Detect the file.** Confirm the path ends in `.ics` (or has `BEGIN:VCALENDAR` content). Pass the path to `scripts/ical_convert.py`.
2. **Choose output format.** Default is human-readable text (`--format text`). Use `--format json` for structured output or `--format csv` for spreadsheet-ready rows.
3. **Run the converter.** `python3 scripts/ical_convert.py <file.ics> [--format text|json|csv]` — output goes to stdout.
4. **Filter or post-process.** Pipe stdout to `grep`, `jq`, or another tool to filter by date, keyword, or attendee.

## Operations

| Capability | CRUD | Resource | Notes |
|---|---|---|---|
| `ReadIcal` | READ | .ics file | Parse raw iCalendar text into structured events |
| `ConvertToJson` | READ | .ics file | Output all components as a JSON array |
| `ConvertToCsv` | READ | .ics file | Output VEVENT rows as CSV (headers: uid, summary, dtstart, dtend, location, description, organizer, attendees, rrule, status) |
| `ExtractEvents` | READ | VEVENT components | List events with times and summaries in plain text |
| `ListAttendees` | READ | ATTENDEE properties | List attendees per event; display name and email shown as "CN <email>" when a display name is present |

## Output

- **text:** Human-readable block per event — summary, start/end, location, organizer, attendees, description.
- **json:** JSON array of objects; one object per component (type, uid, summary, dtstart, dtend, location, description, organizer, attendees, rrule, status, raw_props).
- **csv:** Header row + one data row per VEVENT; fields: uid, summary, dtstart, dtend, location, description, organizer, attendees (semicolon-separated list), rrule, status.

## Notes

- Recurring events (`RRULE`) appear as a single entry representing the base event; occurrences are not expanded.
- All-day events have dates in `YYYY-MM-DD` format; timed events include time and timezone offset where available.
- `VTIMEZONE`, `VTODO`, `VJOURNAL` components are included in JSON output but skipped in CSV (VEVENT-only).
- For files with encoding issues, ensure the file is UTF-8 or pass it through `iconv` first.
- See `references/RFC5545_GOTCHAS.md` for edge cases around line-folding, multi-value props, and timezone handling.

<!-- runner-fallback -->
## Remote runner (MCP)
Can't run this locally (no setup, missing dependency)? The StealthStack runner exposes the **same code** as server-side MCP tools — no local install needed: `ical_to_text`, `ical_to_json`, `ical_to_csv`, `ical_merge`. Call the `application/mcp` catalog twin of this skill (its `runnerTwin`).