Overview

This MCP server exposes your macOS Calendar (Apple Calendar / iCal) over the Model Context Protocol (MCP), letting MCP-compatible clients manipulate calendars using natural language. Instead of manually opening Calendar and clicking through dialogs, a user-facing LLM can read and write events, modify schedules, list availability, and manage multiple calendars by turning conversational intents into calendar operations.

The server is designed for developers who want to integrate calendar control into conversational agents (for example, Claude for Desktop or any MCP client). It translates natural-language scheduling requests into calendar creations, updates, queries, and availability searches, while delegating macOS calendar access to the local Calendar app through Python bindings.

Features

Create events from natural language (title, time, location, notes, reminders)
Update events via natural language (reschedule, change location, transfer calendar)
List events for a time range (day/week/custom)
Find free time slots for a requested duration
Support for recurring events and reminders
Multi-calendar selection and smart calendar suggestions
MCP-compatible server: works with any MCP client
Test suite for development (creates temporary calendars/events)

Installation / Configuration

Prerequisites:

macOS with Calendar configured
Python 3.12+
uv package manager (used to run the packaged dev/runtime)
An MCP-compatible client (Claude for Desktop is commonly used)

Clone and install dependencies:

# Clone repository
git clone https://github.com/Omar-v2/mcp-ical.git
cd mcp-ical

# Install runtime and dependencies with uv
uv sync

Configure an MCP client (example: Claude for Desktop). Add an MCP server entry to your Claude config:

// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "mcp-ical": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp-ical",
        "run",
        "mcp-ical"
      ]
    }
  }
}

Start the MCP server (from the project directory or via uv):

# Run the server
uv run mcp-ical

Important: macOS calendar access permission is required. To ensure the permission prompt appears, launch the MCP client (e.g., Claude) from the terminal:

/Applications/Claude.app/Contents/MacOS/Claude

If you already blocked prompts or need an alternative, the repository includes docs for manual permission configuration (modify system files at your own risk).

Testing (development only):

# Install dev dependencies
uv sync --dev

# Run tests
uv run pytest tests

Available Tools / Resources

GitHub repo: https://github.com/Omar-v2/mcp-ical
Model Context Protocol docs: https://modelcontextprotocol.io
Claude for Desktop (example client): https://claude.ai/download
uv package manager: https://github.com/astral-sh/uv

Server-provided capabilities (exposed via MCP actions):

list_calendars
list_events (by range)
create_event
update_event
delete_event
find_free_slots

Each capability returns structured JSON suitable for LLM consumption and follows MCP message patterns so clients can call tools and get deterministic results.

Use Cases (Concrete Examples)

Create an event from a conversational instruction
- User: “Add a lunch meeting with Sarah tomorrow at noon at Bistro Garden”
- Server action: create_event
- Created event: title “Lunch with Sarah”, start “YYYY-MM-DDT12:00”, location “Bistro Garden”, calendar “default”
Reschedule a meeting
- User: “Move tomorrow’s team meeting to 3 PM”
- Server action: list_events → identify event → update_event
- Result: event start time changed to 3:00 PM, confirmation returned
Find availability for scheduling
- User: “When am I free for a 2-hour meeting next Tuesday?”
- Server action: find_free_slots (duration=120min, range=next Tuesday)
- Response: list of available start/end windows (e.g., 10:00–12:00, 14:00–16:00)
Recurring events
- User: “Set up my weekly team sync every Monday at 9 AM with a 15-minute reminder”
- Server action: create_event with recurrence rules and reminder metadata
Multi-calendar support
- User: “Add dentist appointment to my Personal calendar next Wednesday at 3 PM”
- Server action: create_event with calendar selection

Examples / Quick Reference

Natural language → Typical server operation:

Natural Language	Server Operation
“What’s on my calendar tomorrow?”	list_events for tomorrow
“Schedule a call with Alex Friday 10-11”	create_event (title, start, end)
“Move the 2pm standup to 2:30”	list_events → update_event
“Find a 1-hour slot on Monday afternoon”	find_free_slots (duration=60min, timeframe=Mon afternoon)

Notes and Limitations

Recurring rules for complex/non-standard patterns may not always be perfect.
Reminder timing for all-day recurring events can be inconsistent on macOS.
macOS permission handling requires launching the client from a terminal to prompt for Calendar access; otherwise, manual permission changes may be necessary.

For development, testing, and contributions, consult the repository README and the docs directory for deeper setup, permission workarounds, and test details.

Apple Calendar MCP Server for Natural Language Scheduling