egorkurito/apple-calendar-mcp

开发工具

本页由 AI 翻译，技术细节请以原文为准。查看原文

10 stars 3 forks 质量 68 趋势 18MIT

Repository Install

MCP server for Apple Calendar via native EventKit API with proper recurring event support.

概览

MCP server for Apple Calendar via native EventKit API with proper recurring event support. AppleScript-based calendar integrations fail to correctly expand recurring events — they return the master event instead of individual occurrences. This project uses Apple's native EventKit framework with predicateForEvents, which properly expands recurring events into their individual occurrences within a date range. - — MCP server with 6 tools, Zod validation, JSON-RPC over stdio - — CLI binary using EventKit, returns JSON envelope {status, data, error} - macOS 13+ (Ventura or later) - Swift 5.9+ (included with Xcode 15+) - Node.js 20+ This will automatically download the package, compile the Swift bridge, and register the MCP server. Requires macOS with Xcode or Swift toolchain installed. After installation, grant calendar access: Grant when prompted. If access was previously denied: Connect to Claude Code using one of these methods:

README

以下为原文 README 节选，完整内容请查看原文。

apple-calendar-mcp

MCP server for Apple Calendar via native EventKit API with proper recurring event support.

Why This Exists

AppleScript-based calendar integrations fail to correctly expand recurring events — they return the master event instead of individual occurrences. This project uses Apple’s native EventKit framework with predicateForEvents, which properly expands recurring events into their individual occurrences within a date range.

Architecture

Claude Code ──stdio JSON-RPC──▶ TypeScript MCP Server ──execa──▶ Swift CLI (apple-bridge) ──EventKit──▶ macOS Calendar

TypeScript layer — MCP server with 6 tools, Zod validation, JSON-RPC over stdio
Swift layer — CLI binary using EventKit, returns JSON envelope {status, data, error}

Prerequisites

macOS 13+ (Ventura or later)
Swift 5.9+ (included with Xcode 15+)
Node.js 20+

Installation

Option 1: npm (recommended)

claude mcp add --scope user apple-calendar -- npx apple-calendar-mcp

This will automatically download the package, compile the Swift bridge, and register the MCP server. Requires macOS with Xcode or Swift toolchain installed.

After installation, grant calendar access:

npx apple-calendar-mcp doctor

Grant Full Access when prompted. If access was previously denied:

tccutil reset Calendar
npx apple-calendar-mcp doctor

Option 2: From source

git clone https://github.com/EgorKurito/apple-calendar-mcp.git
cd apple-calendar-mcp
./scripts/build.sh

Grant calendar access:

swift/.build/release/apple-bridge doctor

Connect to Claude Code using one of these methods:

Project-level .mcp.json

Copy .mcp.json.example to .mcp.json in your project and update paths:

{
  "mcpServers": {
    "apple-calendar": {
      "command": "node",
      "args": ["/path/to/apple-calendar-mcp/build/index.js"],
      "env": {
        "APPLE_BRIDGE_BIN": "/path/to/apple-calendar-mcp/swift/.build/release/apple-bridge"
      }
    }
  }
}

User-level CLI registration

claude mcp add --scope user apple-calendar \
  node /path/to/apple-calendar-mcp/build/index.js \
  -e APPLE_BRIDGE_BIN=/path/to/apple-calendar-mcp/swift/.build/release/apple-bridge

MCP Tools

Tool	Description
`get_calendars`	List all calendars with their IDs and colors
`get_events`	Get events in a date range (properly expands recurring events)
`get_today_events`	Get all of today’s events
`search_events`	Search events by title, location, or notes
`create_event`	Create a new calendar event
`delete_event`	Delete an event (single occurrence or all future occurrences)

Verification

# Check system diagnostics
swift/.build/release/apple-bridge doctor

# List calendars
swift/.build/release/apple-bridge calendars

在 GitHub 查看完整 README

安装

npx apple-calendar-mcp doctor

新手？先看 mcpskill.org 教程 →

配置

{
  "mcpServers": {
    "apple-calendar": {
      "command": "node",
      "args": ["/path/to/apple-calendar-mcp/build/index.js"],
      "env": {
        "APPLE_BRIDGE_BIN": "/path/to/apple-calendar-mcp/swift/.build/release/apple-bridge"
      }
    }
  }
}