Macos Calendar MCP

🚀 macOS Calendar MCP Server

A Model Context Protocol (MCP) server that seamlessly integrates with macOS Calendar using AppleScript, eliminating the need for OAuth setup!

✨ Features

• 🍎 Native macOS Integration: Utilizes AppleScript to directly interact with the macOS Calendar.
• 📅 Full Calendar Management: Enables the creation, listing, and searching of calendar events.
• 🚀 Zero Configuration: No need for OAuth or API keys; it works right out of the box.
• 🔧 MCP Compatible: Functions with Claude Code CLI and other MCP clients.
• 📱 Multi - Calendar Support: Works with all your calendars, including Personal, Work, etc.

🚀 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 running for the first time, macOS will prompt 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

📚 Documentation

Available Tools

💻 Usage Examples

Basic Usage

// 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:

• Employs 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 are required.

Supported Calendars

This MCP server works with all macOS Calendar calendars, including:

• Personal calendars
• Work calendars
• Shared calendars
• Subscribed calendars (iCloud, Google, etc.)

🔧 Troubleshooting

Permission Issues

⚠️ Important Note

If you encounter permission errors, follow these steps:

1. Open System Preferences → Security & Privacy → Privacy.
2. Select "Calendar" from the left sidebar.
3. Ensure Terminal (or your app) has access.

AppleScript Errors

• Make sure the Calendar app is installed and accessible.
• Check that calendar names are correct (case - sensitive).
• Verify that date formats match the expected pattern.

Time Zone Issues

⚠️ Important Note

If events appear at incorrect times:

1. Check your system timezone settings.
2. Use the fix - event - times tool to correct existing events.
3. Ensure the 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. Thoroughly test on macOS.
5. Submit a pull request.

📄 License

This project is under the MIT License. See the LICENSE file for details.

🌟 Why This MCP?

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

• ✅ Works immediately without any 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 as everything runs locally.

It's perfect for developers seeking calendar integration without the OAuth hassle!

🔒 Privacy & Security

• ✅ Local Processing: All calendar operations are executed locally on your machine.
• ✅ No Data Upload: Your calendar data never leaves your device.
• ✅ Privacy Focused: No OAuth tokens, no cloud services, and no tracking.

⚠️ Important Note

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