This project provides an MCP (Model Context Protocol) server that enables natural language interaction with macOS Calendars, targeting macOS users seeking a conversational interface for managing their schedules. It offers benefits such as instant event creation, intelligent schedule querying, and seamless event modification through simple text commands.

How It Works

The mcp-ical server acts as a bridge between natural language models and the macOS Calendar application, leveraging the Model Context Protocol (MCP). It utilizes PyObjC to interact with the native macOS Calendar framework, translating user requests like "Add a lunch meeting with Sarah tomorrow at noon" into actual calendar events. The system supports custom calendar selection, location and notes, smart reminders, and recurring events, offering a conversational approach to complex scheduling tasks.

Quick Start & Requirements

• Primary install / run command:
  1. Clone the repository: git clone https://github.com/Omar-V2/mcp-ical.git
  2. Navigate to the directory: cd mcp-ical
  3. Install dependencies: uv sync
• Non-default prerequisites and dependencies: macOS with Calendar app configured, uv package manager, and an MCP-compatible client (Claude for Desktop recommended).
• Setup: Requires configuring Claude for Desktop's claude_desktop_config.json with the server's command and arguments. Crucially, Claude must be launched from the terminal (/Applications/Claude.app/Contents/MacOS/Claude) to trigger macOS calendar permission prompts.
• Links: MCP documentation: https://modelcontextprotocol.io

Highlighted Details

• Event Creation & Updates: Supports detailed event creation (location, notes, reminders) and natural language modification of existing events, including time, date, and calendar transfers.
• Smart Schedule Management: Allows users to query their schedule for specific periods and identify available time slots for new meetings.
• Multi-Calendar Support: Can manage events across multiple calendars, with seamless integration for Google Calendar when synced via iCloud.
• Recurring Events: Enables the setup of recurring events with specified frequencies and reminders.

Maintenance & Community

Contributions are welcomed via a standard fork and pull request workflow. No specific community channels (like Discord or Slack) are listed in the README.

Licensing & Compatibility

• License type: MIT License.
• Compatibility notes: The MIT license is permissive for commercial use and integration into closed-source projects. Google Calendar integration is supported via iCloud sync.

Limitations & Caveats

Known issues include potential inaccuracies with non-standard recurring schedules and a possible one-day offset for reminder timing on recurring all-day events. A critical operational caveat is that the MCP client (e.g., Claude) must be launched from the terminal to correctly request and obtain macOS calendar permissions.