iCal Reader MCP Server

A Model Context Protocol (MCP) server that fetches and parses iCalendar (.ics) files from configured URLs. This server provides easy access to upcoming calendar events through a clean MCP interface.

Features

• 📅 Fetch events from multiple iCal feeds
• ⏰ Get upcoming events within a specified timeframe
• 📆 Functions for weekday scheduling
• 🔄 Real-time calendar updates
• 📝 Detailed event information including location and description
• 🌍 Full timezone support with UTC standardization

Prerequisites

• Python 3.7 or higher
• pip (Python package installer)

Dependencies

The server requires the following Python packages:

fastmcp     # MCP server framework
httpx       # Asynchronous HTTP client
icalendar   # iCalendar file parser
python-dateutil  # Datetime parsing utilities
pytz        # Timezone handling

Installation

1. Clone this repository:

git clone https://github.com/jeromeboivin/iCalReaderMCPServer.git
cd iCalReaderMCPServer

2. Install the required dependencies:

pip install fastmcp httpx icalendar python-dateutil pytz

3. Configure your calendars:

cp calendars_config.json.sample calendars_config.json

4. Edit calendars_config.json with your calendar URLs:

{
    "Personal": "https://calendar.example.com/personal/your-calendar-id.ics",
    "Work": "https://calendar.example.com/work/your-work-calendar.ics"
}

Usage

Starting the Server

To run the server in normal mode:

python ical_reader_mcp_server.py

To run in interactive test mode:

python ical_reader_mcp_server.py --test

Available MCP Tools

1. get_calendar_events

   • Fetches raw event data from specified calendars
   • Parameters:
     • calendar_name (optional): Specific calendar to query
     • days (optional, default=7): Number of days to look ahead

2. get_formatted_calendar_events

   • Returns human-readable formatted event listings
   • Same parameters as get_calendar_events

3. get_next_weekday_events

   • Retrieves events for the next weekday (skipping weekends)
   • Parameters:
     • calendar_name (optional): Specific calendar to query

4. get_week_schedule

   • Generates a formatted weekly schedule
   • Parameters:
     • calendar_name (optional): Specific calendar to query

5. list_available_calendars

   • Returns a list of configured calendars and their descriptions
   • No parameters required

Event Information

Each event includes:

• Summary (title)
• Start and end times (in UTC)
• Location (if available)
• Description (if available)
• Calendar source

Testing

The server includes an interactive test mode that allows you to test all MCP tools from the command line:

python ical_reader_mcp_server.py --test

This mode provides a menu-driven interface to test each tool with custom parameters.

Error Handling

The server includes robust error handling for:

• Missing configuration files
• Invalid calendar URLs
• Malformed iCal data
• Network connection issues
• Invalid parameter values

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is open source and available under the MIT License.