che-ical-mcp

macOS Calendar & Reminders MCP server - Native EventKit integration for complete calendar and task management.

English | 繁體中文

Why che-ical-mcp?

Quick Start

For Claude Desktop

Option A: MCPB One-Click Install (Recommended)

Download the latest .mcpb file from Releases and double-click to install.

Option B: Manual Configuration

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "che-ical-mcp": {
      "command": "/usr/local/bin/che-ical-mcp"
    }
  }
}

For Claude Code (CLI)

Option A: Install as Plugin (Recommended)

The plugin includes slash commands (/today, /week, /quick-event, /remind), skills, and a PreToolUse hook that automatically verifies day-of-week when creating or updating events — preventing date/weekday mismatch errors.

claude plugin add --marketplace psychquant-claude-plugins che-ical-mcp

Note: The plugin wraps the MCP binary with auto-download. If the binary is not found at ~/bin/CheICalMCP, it will be downloaded from GitHub Releases on first use.

Option B: Install as standalone MCP

If you only need the MCP server without plugin features:

# Create ~/bin if needed
mkdir -p ~/bin

# Download the latest release
curl -L https://github.com/kiki830621/che-ical-mcp/releases/latest/download/CheICalMCP -o ~/bin/CheICalMCP
chmod +x ~/bin/CheICalMCP

# Add to Claude Code
# --scope user    : available across all projects (stored in ~/.claude.json)
# --transport stdio: local binary execution via stdin/stdout
# --              : separator between claude options and the command
claude mcp add --scope user --transport stdio che-ical-mcp -- ~/bin/CheICalMCP

💡 Tip: Always install the binary to a local directory like ~/bin/. Avoid placing it in cloud-synced folders (Dropbox, iCloud, OneDrive) as file sync operations can cause MCP connection timeouts.

Build from Source (Optional)

git clone https://github.com/kiki830621/che-ical-mcp.git
cd che-ical-mcp
make release && make install

⚠️ Swift 6 / Xcode 18 users: Do not use swift build directly — upstream MCP SDK has a concurrency error (swift-sdk#214). The Makefile auto-detects this and falls back to Swift 5 language mode.

On first use, macOS will prompt for Calendar and Reminders access - click "Allow".

CLI Mode (No MCP Server)

All 28 tools can be invoked directly from the command line without running the MCP server:

# Flag-based: --key value pairs
CheICalMCP --cli list_events --start_date 2026-03-29 --end_date 2026-03-30

# JSON via stdin
echo '{"tool":"list_calendars","arguments":{}}' | CheICalMCP --cli

# Use with Claude Code via shell
claude -p "Run: ~/bin/CheICalMCP --cli list_events_quick --range today"

Useful for launchd jobs, shell scripts, CI pipelines, and agents that prefer subprocess over MCP protocol. TCC permissions still required — run CheICalMCP --setup first if needed.

All 28 Tools

Installation

Requirements

• macOS 13.0+

• Xcode Command Line Tools (only if building from source)

For Claude Desktop

Method 1: MCPB One-Click Install (Recommended)

1. Download che-ical-mcp.mcpb from Releases

2. Double-click the .mcpb file to install

3. Restart Claude Desktop

Method 2: Manual Configuration

1. Download the binary:

   curl -L https://github.com/kiki830621/che-ical-mcp/releases/latest/download/CheICalMCP -o /usr/local/bin/che-ical-mcp
   chmod +x /usr/local/bin/che-ical-mcp

2. Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

   {
     "mcpServers": {
       "che-ical-mcp": {
         "command": "/usr/local/bin/che-ical-mcp"
       }
     }
   }

3. Restart Claude Desktop

For Claude Code (CLI)

# Create ~/bin if needed
mkdir -p ~/bin

# Download the binary
curl -L https://github.com/kiki830621/che-ical-mcp/releases/latest/download/CheICalMCP -o ~/bin/CheICalMCP
chmod +x ~/bin/CheICalMCP

# Register with Claude Code (user scope = available in all projects)
claude mcp add --scope user --transport stdio che-ical-mcp -- ~/bin/CheICalMCP

Build from Source (Optional)

git clone https://github.com/kiki830621/che-ical-mcp.git
cd che-ical-mcp
make release && make install

# Register with Claude Code
claude mcp add --scope user --transport stdio che-ical-mcp -- ~/bin/CheICalMCP

⚠️ Swift 6 / Xcode 18 使用者： 不要直接使用 swift build — 上游 MCP SDK 有 concurrency 錯誤（swift-sdk#214）。Makefile 會自動偵測並回退到 Swift 5 語言模式。

Grant Permissions

On first use, macOS will prompt for Calendar and Reminders access. Click Allow for both.

⚠️ macOS Sequoia (15.x) Note: The permission dialog is attributed to the parent application that launched the MCP server, not the binary itself. This means:

Environment	Permission Attributed To
Claude Desktop	Claude Desktop.app ✅ (works automatically)
Claude Code in Terminal.app	Terminal.app ✅ (works automatically)
Claude Code in VS Code	VS Code ❌ (may not show dialog)
Claude Code in iTerm2	iTerm2 ✅ (works automatically)

If the permission dialog doesn't appear (common with VS Code), you need to add NSCalendarsFullAccessUsageDescription to VS Code's Info.plist:

# Add calendar usage description to VS Code
/usr/libexec/PlistBuddy -c "Add :NSCalendarsFullAccessUsageDescription string 'VS Code needs calendar access for MCP extensions.'" \
  "/Applications/Visual Studio Code.app/Contents/Info.plist"
/usr/libexec/PlistBuddy -c "Add :NSRemindersFullAccessUsageDescription string 'VS Code needs reminders access for MCP extensions.'" \
  "/Applications/Visual Studio Code.app/Contents/Info.plist"

# Re-sign VS Code (required after Info.plist modification)
codesign -s - -f --deep "/Applications/Visual Studio Code.app"

# Restart VS Code, then the permission dialog will appear

Note: This modification will be overwritten when VS Code updates. You'll need to re-apply it after each VS Code update.

v1.0.0 Features

Flexible Date Parsing

All date parameters now accept 4 formats:

Per-Event Timezone (v1.5.0)

Set the display timezone for individual events — essential for multi-timezone travel itineraries.

"Create a flight departure at 09:14 Berlin time"
→ create_event(title: "Flight LH123", start_time: "2026-04-08T09:14:00", timezone: "Europe/Berlin", ...)

"Update the hotel check-in to Dubai time"
→ update_event(event_id: "...", timezone: "Asia/Dubai")

"Remove the custom timezone from an event"
→ update_event(event_id: "...", clear_timezone: true)

• timezone parameter accepts IANA identifiers (e.g., Europe/Berlin, America/New_York, Asia/Taipei)

• When timezone is provided, naive datetimes (without offset) are interpreted in that timezone

• Event output includes the event's own timezone in timezone field and formats start_date_local/end_date_local accordingly

• Available on create_event, update_event, and create_events_batch

• Undo/redo preserves per-event timezone

Attendees & Organizer (Read-Only)

Event responses include participant information when available. These fields are read-only due to EventKit limitations — they cannot be set or modified through the MCP.

Available in: list_events, search_events, list_events_quick, check_conflicts

attendees (array, optional) — Present when the event has participants. Each attendee object contains:

organizer (object, optional) — Present when the event has an organizer. Contains:

Note: Both fields are omitted when the event has no participants or organizer (e.g., local calendar events created without invitees).

Fuzzy Calendar Matching

Calendar names are now matched case-insensitively. If not found, the error message lists all available calendars.

Enhanced list/delete Tools

• list_events: filter (all/past/future/all_day), sort (asc/desc), limit

• list_reminders: filter (all/incomplete/completed/overdue), sort (due_date/creation_date/priority/title), limit

• delete_events_batch: date range mode (before_date/after_date) + dry_run preview

Breaking Change: list_events and list_reminders now return {events/reminders: [...], metadata: {...}} instead of a plain array.

Usage Examples

Calendar Management

"List all my calendars"
"What's on my schedule next week?"
"Create a meeting tomorrow at 2 PM titled 'Team Sync'"
"Add a dentist appointment on Friday at 10 AM with location '123 Main St'"
"Delete the meeting called 'Cancelled Meeting'"

Reminder Management

"List my incomplete reminders"
"Show all reminders in my Shopping list"
"Add a reminder: Buy milk"
"Create a reminder to call mom tomorrow at 5 PM"
"Mark 'Buy milk' as completed"
"Delete the reminder about groceries"

Reminder Management (v1.5.0)

"Remove the due date from 'Buy groceries'"
→ update_reminder(reminder_id: "...", clear_due_date: true)

Advanced Features (v0.3.0+)

"Search for events containing 'meeting'"
"Search for events with both 'project' AND 'review'"
"What do I have today?"
"Show me this week's schedule"
"Are there any conflicts if I schedule a meeting from 2-3 PM?"
"Create 3 weekly team meetings for the next 3 weeks"
"Copy the dentist appointment to my Work calendar"
"Move all events from 'Old Calendar' to 'New Calendar'"
"Delete all the cancelled events"
"Find duplicate events between 'IDOL' and 'Idol' calendars"

DX Improvements (v1.0.0)

"Show my next 5 upcoming events"
→ list_events(start_date: "2026-02-06", end_date: "2026-12-31", filter: "future", sort: "asc", limit: 5)

"Show my overdue reminders"
→ list_reminders(filter: "overdue")

"Preview which events would be deleted from 'Old Calendar' before 2025"
→ delete_events_batch(calendar_name: "Old Calendar", before_date: "2025-01-01", dry_run: true)

"Create an event at 2 PM" (no need for full ISO8601!)
→ create_event(start_time: "14:00", end_time: "15:00", ...)

Supported Calendar Sources

Works with any calendar synced to macOS Calendar app:

• iCloud Calendar

• Google Calendar

• Microsoft Outlook/Exchange

• CalDAV calendars

• Local calendars

Same-Name Calendar Disambiguation (v0.6.0+)

If you have calendars with the same name from different sources (e.g., "Work" in both iCloud and Google), use the calendar_source parameter:

"Create an event in my iCloud Work calendar"
→ create_event(calendar_name: "Work", calendar_source: "iCloud", ...)

"Show events from my Google Work calendar"
→ list_events(calendar_name: "Work", calendar_source: "Google", ...)

If ambiguity is detected, the error message will list all available sources.

Troubleshooting

SSH Access

macOS TCC (Transparency, Consent, and Control) grants privacy permissions per-application. SSH sessions run under sshd, which is a different security context — so permissions granted to Terminal or Claude Code locally do not carry over to SSH.

Workaround A — Run locally first (recommended):

1. Run CheICalMCP once on the target Mac locally (not over SSH)

2. Grant Calendar and Reminders access when the TCC dialog appears

3. SSH sessions should then inherit the grant for the CheICalMCP binary

Workaround B — Grant Full Disk Access to sshd:

1. Open System Settings → Privacy & Security → Full Disk Access

2. Click +, press ⌘⇧G, type /usr/sbin/sshd, and add it

3. Restart the SSH session

⚠️ Workaround B grants sshd broad file access — only use this on machines you fully control.

launchd / Automation

When running CheICalMCP from launchd, cron, or other non-interactive automation, macOS TCC cannot show permission dialogs. Use --setup to pre-grant permissions:

# Step 1: Run once from Terminal (triggers TCC permission dialog)
CheICalMCP --setup

# Step 2: Grant Calendar & Reminders access in the dialog that appears
# Step 3: The binary now has permission — launchd jobs can use it

Detection: CheICalMCP automatically detects non-interactive sessions (missing TERM env var or direct launchd child) and provides targeted error messages with --setup instructions. This works even for indirect launch chains (launchd → Claude Code → CheICalMCP).

Note: If --setup grants permission but the MCP still fails under launchd, TCC may have associated the permission with the parent process. In that case, manually add CheICalMCP in System Settings → Privacy & Security → Calendar/Reminders.

Technical Details

• Current Version: v1.7.0

• Framework: MCP Swift SDK v0.12.0

• Calendar API: EventKit (native macOS framework)

• Transport: stdio

• Platform: macOS 13.0+ (Ventura and later)

• Tools: 28 tools for calendars, events, reminders, tags, undo/redo, and advanced operations

Version History

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE for details.

Author

Created by Che Cheng (@kiki830621)

If you find this useful, please consider giving it a star!