icalPal MCP Server

# icalPal MCP Server A Model Context Protocol (MCP) server that provides access to macOS Calendar and Reminders data via the [icalPal gem](https://rubygems.org/gems/icalPal). ## Overview This MCP server allows AI assistants to interact with your macOS Calendar and Reminders applications, enabling queries about events, tasks, calendars, and accounts. It uses the icalPal Ruby gem under the hood to access the Calendar and Reminders databases. ## Prerequisites - macOS system with Calendar and Reminders apps - Ruby with the icalPal gem installed - Python 3.8+ with FastMCP - Full Disk Access permission for your terminal/application ### Installing icalPal ```bash gem install icalPal ``` ### Installing Python Dependencies ```bash pip install fastmcp ``` Or using uv: ```bash uv sync ``` ## Setup ### 1. Full Disk Access Permission The icalPal gem requires Full Disk Access to read the Calendar and Reminders databases. Grant this permission by: 1. Open System Settings > Privacy & Security > Full Disk Access 2. Add your terminal application (Terminal.app, iTerm2, etc.) or the application running the MCP server 3. Restart your terminal/application ### 2. Running the Server #### Direct Python execution: ```bash python main.py ``` #### Using Docker: ```bash docker-compose up ``` The server will start on port 8000 by default, or you can configure it using environment variables: - `MCP_PORT`: Port number (default: 8000) - `MCP_TRANSPORT`: Transport type (default: "sse") ## Available Tools ### Calendar Events - **`get_events`** - Retrieve calendar events with various filters (date range, calendars, etc.) - **`get_events_today`** - Get events occurring today - **`get_events_now`** - Get events occurring right now ### Tasks/Reminders - **`get_tasks`** - Retrieve tasks/reminders with filters - **`get_dated_tasks`** - Get tasks with due dates - **`get_undated_tasks`** - Get tasks without due dates ### Calendar Management - **`get_calendars`** - List available calendars - **`get_accounts`** - List calendar accounts ## Error Handling The server provides informative error messages for common issues: - **Permission errors**: Guidance on enabling Full Disk Access - **Database access errors**: Information about Calendar database location - **Invalid arguments**: Clear descriptions of parameter requirements ### Running in Development ```bash # Install dependencies uv sync # Run the server uv run python main.py ``` ### Docker Development ```bash # Build and run with Docker Compose docker-compose up --build # Run in detached mode docker-compose up -d ```