Apple Calendar MCP Server

Model Context Protocol (MCP) server for Apple Calendar integration. Create events, read calendar events, search events, delete events, get today's events, and manage calendars using AppleScript.

Features

• 🚀 Built on reliable MCP patterns from mcp-starter-template
• 🛠️ TypeScript with strict typing and Zod validation
• 🔧 AppleScript integration for native macOS Calendar access
• ⚡ Delimiter-based parsing to avoid JSON errors
• 🎯 Retry mechanisms and comprehensive error handling
• 📅 6 powerful calendar tools for complete calendar management
• 📚 Resource endpoints for calendars and today's events

Available Tools

get_calendars

Get list of all calendars in the Calendar app.

Parameters: None

get_calendar_events

Get events from a specific calendar within a date range.

Parameters:

• calendar_name (string): Name of the calendar to read events from
• days_range (number, optional): Number of days to look ahead (default: 7)

create_event

Create a new calendar event.

Parameters:

• calendar_name (string): Name of the calendar to create event in
• summary (string): Event title/summary
• start_date (string): Start date and time (ISO format)
• end_date (string): End date and time (ISO format)
• location (string, optional): Event location
• description (string, optional): Event description
• all_day (boolean, optional): Whether this is an all-day event

search_events

Search for events by title/summary across all calendars.

Parameters:

• query (string): Search query to match event titles
• days_range (number, optional): Number of days to search (default: 30)

get_today_events

Get all events for today from all calendars.

Parameters: None

delete_event

Delete an event by summary and date.

Parameters:

• calendar_name (string): Name of the calendar containing the event
• event_summary (string): Title/summary of the event to delete
• event_date (string): Start date of the event (ISO format)

Resources

calendar://calendars

JSON resource containing all available calendars.

calendar://today

JSON resource containing all events for today.

Quick Start

1. Install dependencies:

   npm install

2. Build the server:

   npm run build

3. Test the server:

   echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node dist/main.js

4. Add to Claude Desktop config:

   {
     "mcpServers": {
       "apple-calendar": {
         "command": "node",
         "args": ["/Users/your-username/mcp/Remote-MCP-Servers/apple-calendar/dist/main.js"]
       }
     }
   }

5. Grant permissions:

   • Open System Settings → Privacy & Security → Privacy
   • Select "Full Disk Access"
   • Add and enable Claude Desktop
   • Restart Claude Desktop

Development

Adding New Tools

1. Create tool directory: src/tools/your_tool/
2. Add schema file: src/tools/your_tool/schema.ts
3. Add implementation: src/tools/your_tool/index.ts
4. Register in src/tools/index.ts

Technical Implementation

This server features:

• AppleScript Integration: Native Calendar app access via osascript
• Delimiter-based Parsing: Uses ||| and ::: delimiters to avoid JSON parsing errors
• Retry Mechanisms: Automatic retry with exponential backoff for reliability
• Type Safety: Full TypeScript typing with Zod schema validation
• Error Handling: Comprehensive error catching and user-friendly messages

Scripts

npm run build      # Build for production
npm run start      # Start the server (after build)
npm run clean      # Clean build directory
npm run check      # Lint and format code
npm run test       # Run tests

Troubleshooting

"Server failed to start"

• Check build output: npm run build
• Verify file permissions: chmod +x dist/main.js
• Check Claude Desktop config syntax

"Permission denied"

• Ensure Claude Desktop has Full Disk Access permission
• Restart Claude Desktop after permission changes

"Calendar not found"

• Use get_calendars tool to see available calendar names
• Calendar names are case-sensitive and must match exactly

License

MIT

Contributing

This MCP server was generated using the init-mcp.md workflow from the MCP Development Workflows, integrating existing Apple Calendar MCP code into the mcp-starter-template structure.

Refer to /Users/7yank/mcp/Remote-MCP-Servers/MCP_DEVELOPMENT_GUIDE.md for detailed development patterns and best practices.

🎉 Your Apple Calendar MCP server is ready!

Generated using the mcp-starter-template and integrated with existing Apple Calendar code through the FoxyChat MCP workflows.