macOS Calendar MCP Server

A Model Context Protocol (MCP) server for seamless macOS Calendar integration using AppleScript. No OAuth setup required!

Features

• 🍎 Native macOS Integration - Uses AppleScript to interact directly with macOS Calendar

• 📅 Full Calendar Management - Create, list, and search calendar events

• 🚀 Zero Configuration - No OAuth, no API keys, just works out of the box

• 🔧 MCP Compatible - Works with Claude Code CLI and other MCP clients

• 📱 Multi-Calendar Support - Works with all your calendars (Personal, Work, etc.)

Related MCP server: Google Workspace MCP Server

Quick Start

Prerequisites

• macOS (required for AppleScript support)

• Node.js 16+

• Calendar app (pre-installed on macOS)

Installation

1. Clone the repository:

git clone https://github.com/xybstone/macos-calendar-mcp.git
cd macos-calendar-mcp

2. Install dependencies:

npm install

3. Grant permissions:

   • When first run, macOS will ask for Calendar app permissions

   • Grant access to allow the MCP server to manage your calendars

Usage with Claude Code CLI

Add to your .claude_project file:

{
  "mcpServers": {
    "macos-calendar": {
      "command": "node",
      "args": ["/path/to/macos-calendar-mcp/macos-calendar-mcp.js"]
    }
  }
}

Or run directly:

node macos-calendar-mcp.js

Available Tools

Examples

Create an Event

{
  "title": "Team Meeting",
  "startDate": "2025-07-05 14:00",
  "endDate": "2025-07-05 15:00", 
  "calendar": "Work",
  "description": "Weekly team sync",
  "location": "Conference Room A"
}

List Calendars

// Returns all available calendars

Search Events

{
  "query": "meeting",
  "calendar": "Work"
}

Date Format

Use the format: YYYY-MM-DD HH:MM (24-hour format)

Examples:

• 2025-07-05 14:00 (2:00 PM)

• 2025-12-25 09:30 (9:30 AM)

• 2025-07-10 18:00 (6:00 PM)

Time Zone Handling:

• Uses native macOS time handling to avoid timezone conversion issues

• All times are interpreted in your system's local timezone

• No UTC conversion or daylight saving adjustments needed

Supported Calendars

Works with all macOS Calendar calendars including:

• Personal calendars

• Work calendars

• Shared calendars

• Subscribed calendars (iCloud, Google, etc.)

Troubleshooting

Permission Issues

If you get permission errors:

1. Open System Preferences → Security & Privacy → Privacy

2. Select "Calendar" from the left sidebar

3. Ensure Terminal (or your app) has access

AppleScript Errors

• Ensure Calendar app is installed and accessible

• Check calendar names are correct (case-sensitive)

• Verify date formats match the expected pattern

Time Zone Issues

If events appear at wrong times:

1. Check your system timezone settings

2. Use the fix-event-times tool to correct existing events

3. Ensure date format is YYYY-MM-DD HH:MM in 24-hour format

4. The MCP uses native macOS time handling to avoid conversion issues

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Test thoroughly on macOS

5. Submit a pull request

License

MIT License - see LICENSE file for details.

Why This MCP?

Unlike Google Calendar integrations that require complex OAuth setups, this MCP:

• ✅ Works immediately with no configuration

• ✅ Integrates with your existing macOS Calendar setup

• ✅ Supports all calendar sources (iCloud, Google, Exchange, etc.)

• ✅ Requires no internet connection for basic operations

• ✅ Respects your privacy - everything runs locally

Perfect for developers who want calendar integration without the OAuth headache!

Privacy & Security

• ✅ Local Processing: All calendar operations run locally on your machine

• ✅ No Data Upload: Your calendar data never leaves your device

• ✅ Privacy Focused: No OAuth tokens, no cloud services, no tracking

• ⚠️ Private Data: When testing, avoid committing files containing personal events to public repositories

Data Protection

The project includes .gitignore patterns to prevent accidental commits of private event data:

• *events*.json - Event data files

• *meetings*.json - Meeting schedules

• *schedule*.json - Schedule files

• private-*.json - Any private data files