che-ical-mcp

Give Claude native control of macOS Calendar and Reminders. A Swift MCP server built directly on EventKit — 29 tools for events, reminders, tags, batch operations, conflict detection, and undo/redo. Not just calendar events: it drives Reminders and tasks too.

English | 繁體中文

Install

Claude Code — register this repo as a marketplace, then install the plugin. The plugin bundles the `/today`, `/week`, `/quick-event`, `/remind` slash commands and a PreToolUse hook that verifies day-of-week on every event write:

claude plugin marketplace add PsychQuant/che-ical-mcp
claude plugin install che-ical-mcp@che-ical-mcp

Claude Desktop — download the latest `.mcpb` from Releases and double-click to install.

Standalone MCP — the 29-tool server on its own, no plugin extras:

mkdir -p ~/bin
curl -L https://github.com/PsychQuant/che-ical-mcp/releases/latest/download/CheICalMCP -o ~/bin/CheICalMCP && chmod +x ~/bin/CheICalMCP
claude mcp add --scope user --transport stdio che-ical-mcp -- ~/bin/CheICalMCP

On first use, macOS prompts for Calendar and Reminders access — click Allow. Building from source, upgrading in place, or running under SSH / launchd / VS Code? See Installation for the full guide.

Why che-ical-mcp?

All 29 Tools

Calendars (4)

Events (4)

> Recurrence exclusions (#182): `create_event` (and each `create_events_batch` item) accepts `recurrence.excluded_occurrence_dates` to skip specific dates in a recurring series at creation time — applied with best-effort all-or-nothing semantics (any failure removes the entire new series via compensating delete; rollback failure is reported, never silent; the first occurrence cannot be excluded), and one `undo` removes the whole series including exclusions. Known limitation: on idempotent retry, a duplicate recurring series with every requested date already absent is `skipped`, but extra exclusions already present on the existing series (beyond those requested) are not detected.

Reminders (8)

Advanced Features (10) ✨ New in v0.3.0+

Undo/Redo (3) ✨ New in v1.4.0

Installation

The quick paths live at the top of this README. This is the full reference — manual config, source builds, permission edge cases, in-place upgrades, and CLI mode.

Requirements

• macOS 14.0+ (Sonoma or later — required since v1.11.0 for the full TCC permission API)
• Xcode Command Line Tools (only if building from source)

Claude Desktop

One-click (recommended): download the latest `che-ical-mcp-.mcpb` from Releases, double-click, and restart Claude Desktop.

Manual config: download the binary, then point `claude_desktop_config.json` at it.

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

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`, then restart Claude Desktop:

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

Claude Code — plugin (recommended)

claude plugin marketplace add PsychQuant/che-ical-mcp
claude plugin install che-ical-mcp@che-ical-mcp

• Inside Claude Code, the slash equivalents `/plugin marketplace add PsychQuant/che-ical-mcp` and `/plugin install che-ical-mcp@che-ical-mcp` work the same way.
• Add the marketplace through its Git repo (`owner/repo`), not a raw `marketplace.json` URL — the plugin `source` is a same-repo relative path (`./plugin`) that only resolves when added via Git.
• Also bundled in the `psychquant-claude-plugins` aggregator (`claude plugin install che-ical-mcp@psychquant-claude-plugins`); both serve the same versioned binary.
• The wrapper auto-downloads the binary to `~/bin/CheICalMCP` on first use if it isn't already there.

Claude Code — standalone MCP

mkdir -p ~/bin

# If upgrading, remove the old binary first. On macOS 26 the kernel can kill a
# fresh binary that inherits a stale code-signature cache from the old inode —
# one a running MCP process may still be holding open.
rm -f ~/bin/CheICalMCP

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

# --scope user: available in all projects  ·  --transport stdio: local stdin/stdout
claude mcp add --scope user --transport stdio che-ical-mcp -- ~/bin/CheICalMCP

> 💡 Tip: Keep the binary in a local directory like `~/bin/`. Cloud-synced folders (Dropbox, iCloud, OneDrive) can trigger MCP connection timeouts when sync touches the file.

Build from Source (optional)

git clone https://github.com/PsychQuant/che-ical-mcp.git
cd che-ical-mcp
make release && make install
claude mcp add --scope user --transport stdio che-ical-mcp -- ~/bin/CheICalMCP

> ⚠️ Swift 6 / Xcode 18 users: Don't run `swift build` directly — the upstream MCP SDK has a concurrency error (swift-sdk#214). The Makefile auto-detects this and falls back to Swift 5 language mode.

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:

>

>

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

>

> ```bash

> # 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.

Upgrading an existing install

The plugin wrapper auto-downloads on fresh installs but does not replace an existing binary. To upgrade in place:

~/bin/CheICalMCP --self-update

This queries GitHub Releases for the latest tag, downloads the new binary, and atomically replaces the current one. If it is running as an MCP server, restart your MCP host (Claude Desktop / Claude Code) afterward to pick up the new version. Manual fallback: `rm -f ~/bin/CheICalMCP && curl -L https://github.com/PsychQuant/che-ical-mcp/releases/latest/download/CheICalMCP -o ~/bin/CheICalMCP && chmod +x ~/bin/CheICalMCP`.

CLI Mode (no MCP server)

All 29 tools can be invoked directly from the command line, no MCP server required:

# 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

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

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

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

Silent permanent denial after upgrade (#154)

If one service (typically Calendar) returns `access denied` while the other works, and `--print-tcc-path` and System Settings report the permission as granted, you are likely hitting the #154 signature: a TCC row created by a pre-v1.7.1 (ad-hoc-signed) build is pinned to that old build's code hashes. The upgraded Developer ID binary can never match it, and on macOS 26.5+ the OS only allows the healing re-prompt when the binary carries the matching `com.apple.security.personal-information.*` entitlement.

As of v1.14.0+ the startup banner surfaces this directly — a `[drift] TCC.db entry pins a code requirement this binary no longer satisfies` line (#155) — when the Security-framework check can confirm the csreq mismatch. Before that, *every* status-API diagnostic (including the banner) reported green, which is exactly what made this class silent. If you hit the denial through Claude Desktop's `.mcpb` install, the denial message itself now names the real blocker and the working paths instead of the dead-end `--setup` (#158).

Fix: upgrade to v1.11.0 or later (the binary now ships both entitlements), restart the host app (full `Cmd+Q` for Claude Desktop), and approve the permission dialog that appears on the first Calendar/Reminders access. Approving rewrites the TCC row keyed to the Developer ID requirement, so it survives all future upgrades. If you accidentally deny the dialog, re-enable the corresponding toggle in System Settings → Privacy & Security → Calendars or Reminders.

> ⚠️ Erratum for the #108-era workaround: `tccutil reset Calendar com.checheng.CheICalMCP` does not work for a bare (non-bundled) binary — it fails with `OSStatus error -10814` because the binary has no LaunchServices registration. And do not run a bare `tccutil reset Calendar` (without a bundle ID): it wipes Calendar grants for *every* app on the machine and, on a pre-entitlements binary, leaves CheICalMCP permanently unable to re-prompt.

Claude Code updates rotate the host-side grant (#170)

Under a Claude Code native install, the real executable lives at a versioned path (`~/.local/share/claude/versions/`; `~/.local/bin/claude` is just a symlink), and macOS TCC keys the host-side Calendar/Reminders grant to that path. Every Claude Code auto-update rotates the path and silently invalidates the grant — the classic symptom is "worked yesterday, broken right after an update", with System Settings accumulating stale bare-version-number entries (`2.1.202`, `2.1.203`, …).

Fix: trigger any calendar tool call from Claude Code so macOS re-prompts (or re-creates the entry), then toggle the newest version-number entry ON in System Settings → Privacy & Security → Calendars / Reminders. Full checklist: the `troubleshoot-tcc` skill (`/che-ical-mcp:check-tcc`). Root cause is upstream (tracked in #170 — Claude Code would need a stable TCC identity); this repo can only detect and document it.

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).

>

> `--setup` in non-interactive sessions (#143): if you run `--setup` itself from a non-interactive session (no `TERM` / direct launchd child) and permission is still undetermined, `--setup` now skips the request and exits non-zero instead of hanging — a TCC dialog can't appear there, so it prints manual-grant instructions rather than blocking. Run `--setup` from a real Terminal to trigger the dialog. (An already-granted binary still reports success even when re-run non-interactively.)

>

> 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.15.0
• Framework: MCP Swift SDK v0.12.0
• Calendar API: EventKit (native macOS framework)
• Transport: stdio
• Platform: macOS 14.0+ (Sonoma and later — bumped from 13.0 in the post-1.10 cluster per #119)
• Tools: 29 tools for calendars, events, reminders, tags, undo/redo, cleanup, and advanced operations

Version History

Contributing

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

Release Process (for maintainers)

Version numbers live in three places with different semantics:

`scripts/build-mcpb.sh` enforces the first three match; it will fail the build if any drifts. `server.json` is intentionally decoupled because bumping it requires a rebuilt `.mcpb`, a fresh SHA256, and a re-submission — steps that don't happen every source release.

Signing & Notarization (required for macOS 26+)

Starting v1.7.1, release binaries are signed with a Developer ID Application certificate and notarized via Apple's `notarytool`. This is required on macOS 26 — ad-hoc signed binaries cannot trigger Calendar / Reminders TCC permission dialogs there.

Prerequisites (one-time setup):

1. Apple Developer Program enrollment.

2. Developer ID Application certificate installed in login keychain.

3. `notarytool` keychain profile (any name; `che-ical-mcp` is the default the build script looks for).

xcrun notarytool store-credentials che-ical-mcp --apple-id  --team-id 
     # notarytool will prompt for the app-specific password

4. Export your identity for the build script:

export DEVELOPER_ID='Developer ID Application:  ()'
   export NOTARY_PROFILE='che-ical-mcp'   # match what you set up in step 3

Persist these in `~/.zshrc` or a project-local `.envrc` (gitignored). The script intentionally has no defaults for these, so a fresh fork doesn't fail with errors referring to the maintainer's identity.

Per-release flow:

make release-signed     # builds universal binary → signs + notarizes → packages .mcpb
gh release create vX.Y.Z mcpb/server/CheICalMCP mcpb/server/CheICalMCP.sha256 mcpb/che-ical-mcp-X.Y.Z.mcpb mcpb/che-ical-mcp-X.Y.Z.mcpb.sha256 --notes "..."

`make release-signed` runs `scripts/build-mcpb.sh`, which after creating the universal binary calls `scripts/sign-and-notarize.sh`. The signing script does pre-flight checks (cert + notarytool profile) and fails fast with friendly messages if anything's missing. Notarization typically takes 1–15 minutes (`notarytool submit --wait` blocks until Apple finishes).

Verification after build (run all three to confirm end-to-end):

# 1. Signature properties (cert + hardened runtime + team ID)
codesign -dv --verbose=2 mcpb/server/CheICalMCP
# Expected:
#   Authority=Developer ID Application:  ()
#   TeamIdentifier=
#   flags=0x10000(runtime)
#   Signature size in the few thousand bytes range (varies by cert chain)

# 2. Signature integrity
codesign --verify --deep --strict --verbose=2 mcpb/server/CheICalMCP
# Expected: exit 0, no warnings

# 3. Notarization end-to-end (this is the real "Gatekeeper would accept" gate)
spctl -a -vvv -t install mcpb/server/CheICalMCP
# Expected: : accepted; source=Notarized Developer ID
#
# Note on flag choice (verified empirically on macOS 26.4.1, 2026-05-04):
#   -t execute → rejected "code is valid but does not seem to be an app"
#                (Apple's "execute" type expects a .app bundle structure,
#                 not raw Mach-O CLI binaries)
#   -t install → accepted; source=Notarized Developer ID  ← use this
#   -t open    → rejected "Insufficient Context"
#
# Apple's Code Signing Guide describes -t execute as the assessment type for
# "applications and tools", but on macOS 26 raw Mach-O binaries fall through
# the .app bundle check. -t install is the documented assessment type for
# software being installed (which describes how a CLI binary lands in ~/bin),
# and is the type that returns the actual notarization verdict in practice.
# Re-test if Apple changes this behavior in a future macOS update.

Local dev iteration without signing latency:

SKIP_CODESIGN=1 ./scripts/build-mcpb.sh   # ad-hoc signed; do NOT ship the result
make install                              # installs ad-hoc to ~/bin (dev only)

The `build-mcpb.sh` script also auto-skips signing when `DEVELOPER_ID` is unset OR the cert isn't in your keychain — so contributors / CI / forks can build a working unsigned `.mcpb` for testing without manually setting `SKIP_CODESIGN`. (You'll see a clear "Skipping codesign" warning when this happens.)

Signing identity environment:

Known limitation — no stapling: `stapler staple` does not support raw Mach-O binaries (only `.app` / `.pkg` / `.dmg` bundles). After notarization, Gatekeeper will online-check the binary on first launch instead of reading a stapled ticket. End users behind air-gapped networks may see "cannot verify developer" warnings; one launch with network resolves it (Apple caches the verdict). Mitigation: `xcrun stapler staple` on a future `.pkg` wrapper if needed.

Troubleshooting:

• Notarization rejected? `xcrun notarytool log --keychain-profile $NOTARY_PROFILE` shows Apple's reason. The signing script prints the submission ID on every run.
• `codesign` complains about missing identity? `security find-identity -p codesigning -v` to confirm cert is present + valid; `xcrun notarytool history --keychain-profile $NOTARY_PROFILE` to confirm the profile works.
• Cert expired? Re-issue at , install, re-export `DEVELOPER_ID`.
• Security warning: don't unlock signing keychain on shared / untrusted machines. The cert + private key signing artifact is supply-chain critical.

License

MIT License - see LICENSE for details.

Author

Created by Che Cheng (@kiki830621)

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