远程iCal日历协议服务器

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: RRULE series are expanded into individual occurrences within the requested window, honouring EXDATE exclusions, RDATE additions and RECURRENCE-ID modified instances
• Timezone resolution for IANA zones, Microsoft Windows zone names as emitted by Exchange/Outlook (e.g. Pacific Standard Time), and any VTIMEZONE block 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

go build -o remote-ical-mcp ./cmd/server/server.go

Configuration

Create a calendars.yaml or calendars.json file:

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:

{
  "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)

./remote-ical-mcp -transport stdio -config calendars.yaml

HTTP Transport (for testing)

./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:

{
  "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:

{
  "calendar": "work",
  "query": "meeting",
  "start_date": "2025-11-01T00:00:00Z"
}

Event Data Structure

{
  "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