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:

Open System Settings > Privacy & Security > Full Disk Access
Add your terminal application (Terminal.app, iTerm2, etc.) or the application running the MCP server
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

icalPal MCP Server