icalPal MCP Server

A Model Context Protocol (MCP) server that provides access to macOS Calendar and Reminders data via the icalPal gem.

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

gem install icalPal

Installing Python Dependencies

pip install fastmcp

Or using uv:

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:

python main.py

Using Docker:

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

# Install dependencies
uv sync

# Run the server
uv run python main.py

Docker Development

# Build and run with Docker Compose
docker-compose up --build

# Run in detached mode
docker-compose up -d