Apple Events MCP Server

English | 简体中文

macOS üzerinde Apple Reminders ve Calendar ile yerel entegrasyon sağlayan bir Model Context Protocol (MCP) sunucusu. Bu sunucu, Apple Reminders ve Calendar Events'lerle standartlaştırılmış bir arayüz aracılığıyla kapsamlı yönetim yetenekleri sunarak etkileşim kurmanızı sağlar.

[!NOTE] Geleceğe bakış: event — macOS'ta Apple Reminders ve Calendar için saf Swift CLI.

Scripting, otomasyon ve doğrudan terminal kullanımı için, artık bağımsız event CLI'ı öneriyoruz. Bu sunucunun bugün kullandığı aynı EventKit tarafından desteklenen reminder/calendar/list/subtask/tag işlemlerini ortaya koyan ilk sınıf Markdown ve JSON çıktısı içerir. mcp-server-apple-events'in gelecek sürümleri, her iki proje de tek, iyi test edilmiş bir Swift uygulamasını paylaşabilmesi için, bundled EventKitCLI binary yerine event CLI'a bağlı olması planlıyor.

Özellikler

Temel İşlevsellik

• Liste Yönetimi: Tüm reminders ve reminder listelerini gelişmiş filtreleme seçenekleriyle görüntüleyin
• Reminder İşlemleri: Listeler arasında reminders için tam CRUD işlemleri (Create, Read, Update, Delete)
• Zengin İçerik Desteği: Başlıklar, notlar, due tarihler, URL'ler ve tamamlanma durumu için tam destek
• Yerel macOS Entegrasyonu: EventKit framework'ü kullanarak Apple Reminders ile doğrudan entegrasyon

Geliştirilmiş Reminder Özellikleri (v1.3.0)

• Öncelik Desteği: Reminder önceliğini (high/medium/low/none) görsel göstergelerle ayarlayın
• Tekrarlayan Reminders: Esnek tekrarlama kurallarıyla (daily, weekly, monthly, yearly) yinelenen reminders oluşturun
• Konum Tabanlı Tetikleyiciler: Bir konuma varış veya ayrılışta tetiklenen geofence reminders ayarlayın
• Etiketler/Eğiketler: Reminders'ları özel etiketlerle düzenleyin ve listeler arasında kategorizelendirin ve filtreleyin
• Alt Görevler/Kontrol Listeleri: Reminders'a ilerleme izlemeyle kontrol listesi öğeleri ekleyin

Gelişmiş Özellikler

• Akıllı Organizasyon: Otomatik kategorilendirme ve öncelik, due tarih, kategori veya tamamlanma durumuna göre akıllı filtreleme
• Güçlü Arama: Tamamlanma durumu, due tarih aralığı, etiketler ve tam metin araması dahil çok ölçütlü filtreleme
• Toplu İşlemler: Optimize edilmiş veri erişim desenleriyle birden fazla reminder'ın verimli işlenmesi
• İzin Yönetimi: Gerekli macOS sistem izinlerinin otomatik doğrulanması ve istenmesi
• Esnek Tarih İşleme: Birden fazla tarih biçimine (YYYY-MM-DD, ISO 8601) ve saat dilimi farkındalığına sahip destek
• Unicode Desteği: Kapsamlı giriş doğrulaması ile tam uluslararası karakter desteği

Teknik Üstünlük

• Temiz Mimarisi: Bağımlılık enjeksiyonuyla Clean Architecture ilkelerine uyan 4 katmanlı mimari
• Tip Güvenliği: Çalışma zamanı tür kontrolü için Zod şema doğrulaması ile tam TypeScript kapsamı
• Yüksek Performans: Performans kritik Apple Reminders işlemleri için Swift derlenmiş binary'ler
• Sağlam Hata Yönetimi: Ayrıntılı tanılama bilgileriyle tutarlı hata yanıtları
• Repository Deseni: Standardize edilmiş CRUD işlemleriyle veri erişim soyutlaması
• Fonksiyonel Programlama: Uygun olduğunda sabit veri yapılarıyla saf fonksiyonlar

Ön Koşullar

• Node.js 20 veya üstü
• macOS (Apple Reminders entegrasyonu için gerekli)
• Xcode Command Line Tools (Swift kodu derleme için gerekli)
• pnpm (paket yönetimi için önerilir)

macOS İzin Gereksinimleri (Sonoma 14+ / Sequoia 15)

Apple, Reminders ve Calendar izinlerini write-only ve full-access kapsamlarına ayrıldı. Swift bridge, Claude'un erişimi onayladığında hem veri okuyup yazabilmesi için aşağıdaki gizlilik anahtarlarını bildirir:

• NSRemindersUsageDescription
• NSRemindersFullAccessUsageDescription
• NSRemindersWriteOnlyAccessUsageDescription
• NSCalendarsUsageDescription
• NSCalendarsFullAccessUsageDescription
• NSCalendarsWriteOnlyAccessUsageDescription

CLI bir notDetermined yetkilendirme durumu algıladığında, requestFullAccessToReminders / requestFullAccessToEvents çağırır; bu da macOS'u doğru istemi göstermesini tetikler. OS izinleri takip etmeyi kaybederse, ./check-permissions.sh çalıştırarak iletişim kutularını yeniden açın.

Bir Claude araç çağrısı yine de bir izin hatasıyla karşılaşırsa, Node.js katmanı otomatik olarak minimal bir AppleScript (osascript -e 'tell application "Reminders" …') çalıştırarak iletişim kutusunu görünür hale getirir ve ardından Swift CLI'ı bir kez yeniden dener.

Takvim Okuma Hatalarını Giderme

Failed to read calendar events görürseniz, Takvim'in Full Calendar Access olarak ayarlandığını doğrulayın:

• System Settings > Privacy & Security > Calendars açın
• Bu MCP sunucusunu başlatan uygulamayı bulun (örneğin Terminal veya Claude Desktop)
• Erişimi Full Calendar Access olarak değiştirin

./check-permissions.sh çalıştırabilirsiniz (artık Reminders ve Calendars erişimini doğrular).

Doğrulama komutu

pnpm test -- src/swift/Info.plist.test.ts

Test paketi, binary'i göndermeden önce tüm gerekli kullanım açıklama dizelerinin mevcut olduğundan emin olur.

macOS 26 (Tahoe) üzerinde could not build module 'Foundation' Sorunlarını Giderme

pnpm build başarısız olursa could not build module 'Foundation' ile (veya SDK is not supported by the compiler), Swift araç zinciri macOS 26 SDK'sının gerektirdiğinden daha eski. macOS 26+ SDK, Swift 6.3 veya daha yeni gerektiren bir Foundation.swiftinterface ile gelir; ilk macOS 26 noktası sürümleriyle gelen Command Line Tools, Swift 6.2.x içerir ve bunu ayrıştıramaz. issue #85 bölümüne bakın.

pnpm build:swift artık bu uyuşmazlığı tespit eder ve aynı çözümü yazdırır, ancak manuel olarak çarparsanız:

1. App Store'dan Xcode 26.x yükleyin (Swift 6.3+ ile gelir) veya
2. Command Line Tools'u Swift 6.3+ ile gelen bir sürüme güncelleyin:

   softwareupdate --list
   sudo softwareupdate -i "Command Line Tools for Xcode-<latest>"
   

3. Her ikisi de yüklenirse, xcode-select işaretçisini tam Xcode'a ayarlayın:

   sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
   

Şu şekilde doğrulayın:

xcrun swiftc --version          # Apple Swift sürümü 6.3 veya daha yeni bildirilmeli
xcrun --show-sdk-version        # macOS ana sürümünüzle eşleşmeli

Hızlı Başlangıç

Sunucuyu npx kullanarak doğrudan çalıştırabilirsiniz:

npx mcp-server-apple-events

Yapılandırma

Cursor'u Yapılandırma

1. Cursor'u açın

2. Cursor ayarlarını açın

3. Kenar çubuğunda "MCP" seçeneğini tıklayın

4. "Add new global MCP server" tıklayın

5. Sunucuyu aşağıdaki ayarlarla yapılandırın:

   {
     "mcpServers": {
       "apple-reminders": {
         "command": "npx",
         "args": ["-y", "mcp-server-apple-events"]
       }
     }
   }
   

ChatWise'ı Yapılandırma

1. ChatWise'ı açın
2. Ayarlar'a gidin
3. Tools bölümüne gidin
4. "+" düğmesine tıklayın
5. Aracı aşağıdaki ayarlarla yapılandırın:
   • Type: stdio
   • ID: apple-reminders
   • Command: mcp-server-apple-events
   • Args: (boş bırakın)

Claude Desktop'u Yapılandırma

Apple Events MCP sunucusunu tanıması için Claude Desktop'u yapılandırmanız gerekir. Yapılandırmaya erişmenin iki yolu vardır:

Seçenek 1: Claude Desktop Kullanıcı Arayüzü Aracılığıyla

1. Claude Desktop uygulamasını açın
2. Sol üst menü çubuğundan Developer Mode'u etkinleştirin
3. Ayarlar'ı açın ve Developer Option'a gidin
4. claude_desktop_config.json dosyasını açmak için Edit Config düğmesine tıklayın

Seçenek 2: Doğrudan Dosya Erişimi

macOS için:

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows için:

code %APPDATA%\Claude\claude_desktop_config.json

2. Sunucu Yapılandırması Ekle

claude_desktop_config.json dosyasına aşağıdaki yapılandırmayı ekleyin:

Seçenek A: npx Kullanma (önerilir)

{
  "mcpServers": {
    "apple-reminders": {
      "command": "npx",
      "args": ["-y", "mcp-server-apple-events"]
    }
  }
}

Seçenek B: Yerel derleme kullanma

Projeyi yerel olarak derlediyseniz, dist/index.js yoluna node kullanın:

{
  "mcpServers": {
    "apple-reminders": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-apple-events/dist/index.js"]
    }
  }
}

Yerel MCP sunucuları bağlama hakkında daha fazla bilgi için resmi MCP belgelerine bakın.

3. Claude Desktop'u Yeniden Başlat

Değişikliklerin etkili olması için:

1. Claude Desktop'u tamamen kapatın (sadece pencereyi kapatmayın)
2. Claude Desktop'u yeniden başlatın
3. Apple Events sunucusunun bağlı olduğunu doğrulamak için araç simgesini arayın

Kullanım Örnekleri

Yapılandırıldıktan sonra, Claude'dan Apple Reminders'ınızla etkileşim kurmasını isteyebilirsiniz. İşte bazı örnek istemler:

Reminders Oluşturma

"Buy groceries" reminderi yarın saat 17:00 için oluştur.
"Call mom" reminderi ekle, not ekle "Ask about weekend plans".
"Work" listemde "Submit report" reminderi yarları cuma günü için oluştur.
URL ile reminder oluştur "Check this website: https://google.com".

Reminder'ları Öncelik ile Oluşturma

"Finish quarterly report" reminderi cuma günü için yüksek öncelik ile oluştur.
"Call client back" reminderi bugün için acil yüksek öncelik ile ekle.
"Review documents" reminderi orta öncelik ile oluştur.

Tekrarlayan Reminder'lar Oluşturma

Saat 9'da "Take medication" reminderi günlük oluştur.
Pazartesi günü "Team standup meeting" reminderi haftalık ekle.
"Pay rent" reminderi ayda bir 1'inde oluştur.
15 Mart'ta vergi dosyası açmak için yıllık reminder ayarla.

Konum Tabanlı Reminder'lar Oluşturma

Süpermarkete vardığımda "Buy milk" hatırlatması yap.
Evime geldiğimde "Check mailbox" reminderi oluştur.
Ofisten ayrılırken "Submit timesheet" reminderi ekle.

Etiketlerle Reminder'lar Oluşturma

work ve urgent etiketleriyle "Review PR" reminderi oluştur.
personal ve shopping etiketleriyle "Buy birthday gift" reminderi ekle.
Etiketler ile reminder oluştur: project-alpha, backend, review.

Alt Görevlerle Reminder'lar Oluşturma

Alt görevlerle "Grocery shopping" reminderi oluştur: milk, eggs, bread, butter.
Kontrol listesi öğeleriyle "Pack for trip" reminderi ekle: passport, charger, clothes, toiletries.
Alt görevlerle "Sprint planning" oluştur: review backlog, estimate stories, assign tasks.

Alt Görevleri Yönetme

"Grocery shopping" reminderi için alt görevleri göster.
"milk" alt görevini tamamlandı olarak işaretle.
"cheese" alt görevi ekleme yapı reminderi için ekle.
Packing listem reminderi'ndeki alt görevleri yeniden sırala.

Reminders'ları Filtreleme

Tüm yüksek öncelikli reminders'ı göster.
"work" etiketi ile etiketlenen reminders göster.
Yalnızca tekrarlayan reminders göster.
Konum tabanlı reminders bulunuz.
Tamamlanmamış alt görevler içeren reminders göster.

Reminder'ları Güncelle

"Buy groceries" reminderi başlığını "Buy organic groceries" olarak güncelle.
"Call mom" reminderi bugün saat 18:00'e ayarla.
"Submit report" reminderi güncelleyin ve tamamlandı olarak işaretleyin.
"Buy groceries" reminderi notlarını "Don't forget milk and eggs" olarak değiştir.
"Finish report" reminderi'nde önceliği yüksek olarak ayarla.
"Review PR" reminderi'ne "urgent" etiketi ekle.

Reminder'ları Yönet

Tüm reminders'ımı göster.
"Shopping" listemden reminders'ı listele.
Tamamlanmış reminders'ımı göster.

Listelerle Çalışma

Tüm reminder listelerimi göster.
"Work" listemden reminders göster.

Sunucu şunları yapacaktır:

• Doğal dil isteklerinizi işleyin
• Apple'ın yerel Reminders uygulaması ile etkileşim kurun
• Biçimlendirilmiş sonuçları Claude'a döndürün
• macOS ile yerel entegrasyonunu koruyun

Yapılandırılmış İstem Kitaplığı

Sunucu, MCP ListPrompts ve GetPrompt uç noktaları aracılığıyla ortaya konan birleştirilmiş bir istem kaydıyla birlikte gelir. Her şablon, aşağı akış asistanlarının kırılgan serbest biçim örnekleri yerine öngörülebilir iskeleler alması için bir misyon, bağlam girdileri, numaralandırılmış süreç, kısıtlamalar, çıktı biçimi ve kalite çubuğu paylaşır.

• daily-task-organizer — isteğe bağlı today_focus (bugün en çok başarmak istediğiniz şey) girdisi, öncelik işini kurtarma zamanıyla dengeleyen aynı gün yürütme planı oluşturur. Akıllı görev kümelemesi, odak bloğu planlama, otomatik reminder listesi organizasyonu ve birçok today due reminders sabit yuvaları ihtiyaç olduğunda takvim zaman bloklarını otomatik oluşturma destekler. Hızlı Kazanımlar, her reminder'ın due zaman damgasında biten "Focus Sprint — [Outcome]" 15 dakikalık tutmaları olur, Standard görevler aynı due zaman penceresine sabitlenen 30, 45 veya 60 dakikalık olaylara eşlenir.
• smart-reminder-creator — isteğe bağlı task_idea (yapmak istediğiniz şeyin kısa açıklaması) en uygun şekilde planlanmış reminder yapısı oluşturur.
• reminder-review-assistant — isteğe bağlı review_focus (örneğin gecikmeli veya liste adı) mevcut reminders'ı denetleyip optimize etmek için.
• weekly-planning-workflow — isteğe bağlı user_ideas (bu hafta başarmak istediğiniz düşünceler ve fikirler) mevcut listelerle bağlantılı zaman bloklarıyla Pazartesi'den Pazar'a sıfırlamaya kılavuzluk eder.

Tasarım kısıtlamaları ve doğrulama

• İstemler kasıtlı olarak yerel Apple Reminders yetenekleriyle sınırlandırılmıştır (üçüncü taraf otomasyonları yok) ve geri alınamaz eylemleri taahhüt etmeden önce eksik bağlam istenir.
• Paylaşılan biçimlendirme, çıktıları istemci uygulamalarında ekstra ayrıştırma yapıştırıcısı olmadan Markdown bölümleri veya tablolar olarak oluşturulabilir hale getirir.
• İstem kopyasını değiştirdiğiniz her zaman meta veri, şema uyumluluğu ve anlatı montajını doğrulamak için pnpm test -- src/server/prompts.test.ts çalıştırın.

Mevcut MCP Araçları

Bu sunucu artık Apple Reminders ve Calendar alanlarını yansıtan hizmet kapsamlı MCP araçları ortaya koymaktadır. İşlenmek istediğiniz kaynakla eşleşen tanımlayıcıyı kullanın:

Reminder Tasks Aracı

Araç Adı: reminders_tasks

Öncelik, alarmlar, tekrarlama kuralları, başlangıç/due/tamamlanma tarihleri, konum tetikleyicileri, etiketler ve alt görevler dahil olmak üzere tam CRUD desteğiyle bireysel reminder görevlerini yönetir.

Eylemler: read, create, update, delete

Ana İşleyici Fonksiyonları:

• handleReadReminders() - Filtreleme seçenekleriyle reminders'ı oku
• handleCreateReminder() - Yeni reminders oluştur
• handleUpdateReminder() - Mevcut reminders'ı güncelle
• handleDeleteReminder() - Reminders sil

Eylem Parametreleri

Read Eylemi (action: "read"):

• id (isteğe bağlı): Okumak için belirli reminder'ın benzersiz tanımlayıcısı
• filterList (isteğe bağlı): Gösterilecek reminder listesinin adı
• showCompleted (isteğe bağlı): Tamamlanmış reminders'ı dahil et (varsayılan: false)
• search (isteğe bağlı): Reminders'ı başlık veya içeriğe göre filtrelemek için arama terimi
• dueWithin (isteğe bağlı): Due tarih aralığına göre filtrele ("today", "tomorrow", "this-week", "overdue", "no-date")
• filterPriority (isteğe bağlı): Öncelik düzeyine göre filtrele ("high", "medium", "low", "none")
• filterRecurring (isteğe bağlı): Gerçek olduğunda yalnızca tekrarlayan reminders göster
• filterLocationBased (isteğe bağlı): Gerçek olduğunda yalnızca konum tabanlı reminders göster
• filterTags (isteğe bağlı): Etiketlere göre filtrele (reminder tüm belirtilen etiketlere sahip olmalı)

Create Eylemi (action: "create"):

• title (gerekli): Reminder başlığı
• startDate (isteğe bağlı): 'YYYY-MM-DD' veya 'YYYY-MM-DD HH:mm:ss' biçiminde başlangıç tarihi
• dueDate (isteğe bağlı): 'YYYY-MM-DD' veya 'YYYY-MM-DD HH:mm:ss' biçiminde due tarih
• targetList (isteğe bağlı): Eklenecek reminder listesinin adı
• note (isteğe bağlı): Reminder'a eklenecek not metni
• url (isteğe bağlı): Reminder'la ilişkili URL
• location (isteğe bağlı): Konum metni (EKCalendarItem.location) (geofence tetikleyicisi değil)
• priority (isteğe bağlı): Öncelik düzeyi (0=none, 1=high, 5=medium, 9=low)
• alarms (isteğe bağlı): Alarm nesneleri dizisi (aşağıda Alarm Nesnesine bakın)
• recurrenceRules (isteğe bağlı): Tekrarlama kuralları dizisi (aşağıda Tekrarlama Kurallarına bakın)
• recurrence (isteğe bağlı): Eski tek tekrarlama kural nesnesi (bir öğeli recurrenceRules için kısayol)
• locationTrigger (isteğe bağlı): Konum tetikleyici nesnesi (aşağıda Konum Tetikleyicileri bölümüne bakın)
• tags (isteğe bağlı): Reminder'a eklenecek etiketler dizisi
• subtasks (isteğe bağlı): Reminder'la birlikte oluşturulacak alt görev başlıkları dizisi

Update Eylemi (action: "update"):

• id (gerekli): Güncellenecek reminder'ın benzersiz tanımlayıcısı
• title (isteğe bağlı): Reminder için yeni başlık
• startDate (isteğe bağlı): Yeni başlangıç tarihi
• dueDate (isteğe bağlı): 'YYYY-MM-DD' veya 'YYYY-MM-DD HH:mm:ss' biçiminde yeni due tarih
• note (isteğe bağlı): Yeni not metni
• url (isteğe bağlı): Reminder'a eklenecek yeni URL
• location (isteğe bağlı): Yeni konum metni (temizlemek için boş dize olarak ayarla)
• completed (isteğe bağlı): Reminder'ı tamamlandı/tamamlanmadı olarak işaretle
• completionDate (isteğe bağlı): Açık tamamlanma tarihi/saati ayarla
• targetList (isteğe bağlı): Reminder'ı içeren listenin adı
• priority (isteğe bağlı): Yeni öncelik düzeyi (0=none, 1=high, 5=medium, 9=low)
• alarms (isteğe bağlı): Alarmları bu dizi ile değiştir
• clearAlarms (isteğe bağlı): Tüm alarmları kaldırmak için true olarak ayarla
• recurrenceRules (isteğe bağlı): Tekrarlama kurallarını bu dizi ile değiştir
• recurrence (isteğe bağlı): Eski tek tekrarlama kural (bir öğeli recurrenceRules için kısayol)
• clearRecurrence (isteğe bağlı): Tekrarlamayı kaldırmak için true olarak ayarla
• locationTrigger (isteğe bağlı): Yeni konum tetikleyici
• clearLocationTrigger (isteğe bağlı): Konum tetikleyicisini kaldırmak için true olarak ayarla
• tags (isteğe bağlı): Bu dizi ile tüm etiketleri değiştir
• addTags (isteğe bağlı): Eklenecek etiketler (mevcut olanlarla birleşir)
• removeTags (isteğe bağlı): Kaldırılacak etiketler

Delete Eylemi (action: "delete"):

• id (gerekli): Silinecek reminder'ın benzersiz tanımlayıcısı

Alarm Nesnesi

{
  "relativeOffset": -900,            // Saniyeler (due/start'a göreli); negatif = önce
  "absoluteDate": "2025-11-04T09:00:00+08:00", // Mutlak tetikleyici zamanı (isteğe bağlı)
  "locationTrigger": {               // Geofence tetikleyici (isteğe bağlı)