Apple Calendar MCP Server

A comprehensive Model Context Protocol (MCP) server that provides Claude with full access to Apple Calendar for smart scheduling, calendar management, and time management assistance.

Features

Calendar Management

• list_calendars - List all available calendars

• create_calendar - Create new calendars

• delete_calendar - Delete calendars

• rename_calendar - Rename existing calendars

Event Operations

• create_event - Create events with natural language date parsing

  • Supports "tomorrow at 3pm", "next Friday", "in 2 hours", etc.

• list_events - List events in a specific calendar

• list_all_events - List events across all calendars

• search_events - Search for events by keyword (searches title, location, description)

• update_event - Update event properties

• delete_event - Delete events

• move_event - Move events between calendars

Smart Scheduling

• find_free_time - Find available time slots

  • Optional business hours filter (9am-5pm)

• check_conflicts - Check for scheduling conflicts

• suggest_optimal_time - AI-powered time suggestions with preferences

Templates

• create_template - Save event configurations as reusable templates

• use_template - Create events from templates

• list_templates - View all saved templates

• delete_template - Remove templates

Analytics

• analyze_schedule - Get insights on:

  • Meeting density (meetings per day)

  • Total time spent in meetings

  • Daily breakdown of schedule

Installation

Prerequisites

• macOS (required for Apple Calendar)

• Node.js 20+ and npm

• Apple Calendar app

• Claude Code CLI

Setup

1. Clone/Install the server:

   cd ~/mcp-servers/calendar npm install npm run build

2. Grant Calendar Access:

   • System Preferences > Security & Privacy > Privacy > Automation

   • Enable Terminal (or your terminal app) to control Calendar

3. Configure Claude Code:

   The server is already configured in: ~/Library/Application Support/Claude/claude_desktop_config.json

   { "mcpServers": { "apple-calendar": { "command": "node", "args": [ "/Users/josii/mcp-servers/calendar/dist/index.js" ] } } }

4. Restart Claude Code:

   The server will auto-start when Claude Code launches.

Usage Examples

Basic Calendar Operations

Creating Events

Natural Language Date Parsing

The server understands:

• "tomorrow at 3pm"

• "next Friday"

• "in 2 hours"

• "Jan 15 at 10:30am"

• "this weekend"

Smart Scheduling

Searching Events

Using Templates

Analytics

Architecture

Technical Details

Natural Language Processing

• Uses chrono-node for parsing natural language dates

• Supports relative dates, absolute dates, and common phrases

• Automatically handles time zones and ambiguity

AppleScript Integration

• Direct osascript calls for reliable Calendar access

• Proper date formatting for AppleScript

• String escaping to prevent injection attacks

• Error handling for Calendar API failures

Data Storage

• SQLite database for templates and history

• Settings for default preferences

• Undo history (last 100 operations)

Conflict Detection

• Efficient time slot overlap checking

• Free time finding with configurable intervals

• Business hours filtering

• Optimal time suggestions based on preferences

Configuration

Default settings (stored in SQLite):

• default_calendar: "life"

• default_event_duration: 1 hour (3600000 ms)

• business_hours_start: 9 (9am)

• business_hours_end: 17 (5pm)

Development

Build

Development Mode (with auto-reload)

Debug with MCP Inspector

Troubleshooting

"Calendar access not allowed"

Solution: Grant automation permissions in System Preferences > Security & Privacy > Privacy > Automation

Server not connecting

1. Check logs in ~/Library/Logs/Claude/

2. Verify build succeeded: npm run build

3. Test directly: npx tsx src/index.ts

4. Ensure Calendar.app is not in a broken state

Date parsing fails

• chrono-node handles most common formats

• For edge cases, use explicit formats like "2024-01-15 10:30am"

• Check the input format in the error message

Events not appearing

1. Verify calendar name matches exactly (case-sensitive)

2. Check if Calendar.app is running

3. Refresh Calendar.app view

Future Enhancements

Potential features for v2:

• Recurring events with RRULE support

• Attendee management

• Location autocomplete

• Video conferencing link generation

• iCal import/export

• Proactive schedule optimization

• ML-based event categorization

License

MIT

Author

Built for Claude Code MCP integration