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.)
Quick Start
Prerequisites
- macOS (required for AppleScript support)
- Node.js 16+
- Calendar app (pre-installed on macOS)
Installation
- Clone the repository:
git clone https://github.com/xybstone/macos-calendar-mcp.git
cd macos-calendar-mcp
- Install dependencies:
npm install
- 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
| Tool | Description | Parameters |
|---|---|---|
list-calendars | List all available calendars | None |
create-event | Create a new calendar event | title, startDate, endDate, calendar, description, location |
list-today-events | List today's events | calendar (optional) |
search-events | Search events by keyword | query, calendar (optional) |
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:
- Open System Preferences → Security & Privacy → Privacy
- Select "Calendar" from the left sidebar
- 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:
- Check your system timezone settings
- Use the
fix-event-timestool to correct existing events - Ensure date format is
YYYY-MM-DD HH:MMin 24-hour format - The MCP uses native macOS time handling to avoid conversion issues
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Test thoroughly on macOS
- 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 filesprivate-*.json- Any private data files