Remote iCal MCP Server
An MCP (Model Context Protocol) server that exposes remote ICS (iCalendar) calendar data through a standardized interface.
Features
- Fetch and parse remote ICS calendar files
- Support for multiple configured calendars or ad-hoc URLs
- Recurrence expansion:
RRULEseries are expanded into individual occurrences
within the requested window, honouringEXDATEexclusions,RDATEadditions
andRECURRENCE-IDmodified instances - Timezone resolution for IANA zones, Microsoft Windows zone names as emitted by
Exchange/Outlook (e.g.Pacific Standard Time), and anyVTIMEZONEblock
defined in the feed itself - Overlap-based date range filtering, so events already in progress at the start
of the window are included - Text search across events
- Full event details including:
- Attendees and organizer
- Categories/tags
- All-day event detection
- Location, status, and descriptions
Installation```bash
go build -o remote-ical-mcp ./cmd/server/server.go
## Configuration
Create a `calendars.yaml` or `calendars.json` file:
**YAML:**```yaml
calendars:
- name: work
description: Work calendar
url: https://example.com/work-calendar.ics
- name: personal
description: Personal calendar
url: https://example.com/personal-calendar.ics
JSON:```json
{
"calendars": [
{"name": "work", "description": "Work calendar", "url": "https://example.com/work-calendar.ics"},
{"name": "personal", "description": "Personal calendar", "url": "https://example.com/personal-calendar.ics"}
]
}
`description` is optional and is surfaced to clients through `list_calendars`.
## Usage
### Stdio Transport (for MCP clients)```bash
./remote-ical-mcp -transport stdio -config calendars.yaml
HTTP Transport (for testing)```bash
./remote-ical-mcp -transport http -port 8080 -config calendars.yaml
## Available Tools
### `list_calendars`
List all configured calendars, with their names and descriptions.
**Parameters:** None
### `list_events`
Fetch and list events from a calendar. Recurring series are expanded into
individual occurrences within the window.
**Parameters:**
- `calendar` (required): Calendar name or direct ICS URL
- `start_date` (optional): Only return events overlapping on or after this time (RFC3339). Defaults to one year ago.
- `end_date` (optional): Only return events overlapping before this time (RFC3339). Defaults to two years ahead.
The range is an overlap test, not a start-time test: an event that begins before
`start_date` but is still running after it is included. The defaults exist
because expanding an open-ended recurrence rule requires a bounded window.
**Example:**```json
{
"calendar": "work",
"start_date": "2025-01-01T00:00:00Z",
"end_date": "2025-12-31T23:59:59Z"
}
search_events
Search for events matching a query string.
Parameters:
- calendar (required): Calendar name or direct ICS URL
- query (required): Search term for summary, description, or location
- start_date (optional): Only search events overlapping on or after this time (RFC3339)
- end_date (optional): Only search events overlapping before this time (RFC3339)
Example:```json
{
"calendar": "work",
"query": "meeting",
"start_date": "2025-11-01T00:00:00Z"
}
## Event Data Structure```json
{
"uid": "event-unique-id",
"summary": "Event Title",
"description": "Event description",
"location": "Meeting Room A",
"start": "2025-11-26T10:00:00Z",
"end": "2025-11-26T11:00:00Z",
"status": "CONFIRMED",
"organizer": "mailto:organizer@example.com",
"attendees": ["mailto:attendee1@example.com", "mailto:attendee2@example.com"],
"categories": ["Work", "Important"],
"recurrence_rule": "FREQ=WEEKLY;BYDAY=MO,WE,FR",
"all_day": false,
"recurring": true
}
start and end are RFC3339 timestamps carrying the event's original UTC
offset, so a calendar holding meetings in several timezones reports each in its
own. recurring is true when the occurrence was generated by expanding an
RRULE; recurrence_rule carries the rule it came from.
Environment Variables
LOG_LEVEL: Set logging level (debug, info, warn, error). Default: info
License
MIT
