mcp-ical-swift

Локальный MCP-сервер для Apple Calendar, который использует скомпилированный Swift-бинарный файл для обхода ограничений TCC в macOS Sequoia.

Зачем это нужно

В macOS Sequoia (26.x) фоновые процессы не могут получить доступ к Календарю через стандартный механизм TCC (Transparency, Consent, and Control):

• EventKit из Python (например, PyObjC) требует kTCCServiceCalendar, который можно предоставить только через системное диалоговое окно, которое фоновые процессы не могут вызвать. В Системных настройках > Конфиденциальность и безопасность > Календари на Sequoia нет кнопки +.

• AppleScript через osascript требует kTCCServiceAppleEvents (разрешение на автоматизацию), которое привязывается к вызывающему бинарному файлу (обычно node или bun). Прямое редактирование базы данных TCC игнорируется проверками целостности демона TCC.

• icalBuddy и другие инструменты Homebrew используют EventKit внутри себя и сталкиваются с той же проблемой.

Скомпилированный Swift-бинарный файл (swiftc) работает, потому что он создает исполняемый файл Mach-O с подписью Apple, который наследует TCC Календаря от системного набора инструментов Swift. Когда Node/Bun запускает этот файл через execFileSync, EventKit сообщает authorizationStatus = .fullAccess и возвращает данные календаря.

Возможности

• Список всех календарей

• Список событий в заданном диапазоне дат

• Поиск событий по ключевым словам

• Создание новых событий (с поддержкой календаря, местоположения, заметок и событий на весь день)

• Обновление существующих событий

• Получение полной информации о событии по UID

• Удаление событий

• Работает полностью локально через stdio — без сети, без API-ключей, без облака

Предварительные требования

• macOS Sequoia (26.x) или новее

• Bun 1.1+

• Xcode Command Line Tools (xcode-select --install) для swiftc

• Данные календаря в Apple Calendar (iCloud, Exchange или локальные календари)

Установка

git clone https://github.com/Sealjay/mcp-ical-swift.git
cd mcp-ical-swift
bun install
bun run build

Скрипт build компилирует src/calendar-reader.swift в bin/calendar-reader.

Конфигурация MCP-клиента

Claude Code

claude mcp add --transport stdio ical --scope user -- bun run /absolute/path/to/mcp-ical-swift/src/index.ts

OpenClaw

{
  "mcp": {
    "servers": {
      "ical": {
        "command": "bun",
        "args": ["run", "/absolute/path/to/mcp-ical-swift/src/index.ts"]
      }
    }
  }
}

Claude Desktop

Добавьте в claude_desktop_config.json:

{
  "mcpServers": {
    "ical": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/mcp-ical-swift/src/index.ts"]
    }
  }
}

Инструменты

Как это работает

MCP Client (Claude, OpenClaw, etc.)
  --> stdio --> Bun MCP server (src/index.ts)
    --> execFileSync --> compiled Swift binary (bin/calendar-reader)
      --> EventKit framework --> Apple Calendar data

Swift-бинарный файл компилируется один раз (bun run build) и вызывается синхронно для каждого вызова инструмента. Он выводит JSON в stdout, который MCP-сервер Bun оборачивает в результаты инструментов MCP. Сервер использует execFileSync (не выполнение в оболочке), чтобы избежать рисков инъекций.

Ключевая идея: бинарные файлы, скомпилированные через swiftc, подписаны Apple и наследуют TCC Календаря от системного набора инструментов. Это обходит ограничения TCC, которые блокируют доступ к календарям для Node, Bun, Python и AppleScript в фоновых контекстах.

Конфиденциальность и безопасность

• Этот сервер по умолчанию получает доступ ко всем календарям в системе (iCloud, Exchange, локальные, общие, подписки). Вы можете фильтровать их по имени календаря для каждого запроса, используя необязательный параметр calendar в list_events и search_events.

• Заметки к событиям возвращаются в ответах и могут содержать конфиденциальные данные (PIN-коды встреч, пароли, личные данные). Учитывайте это при предоставлении доступа MCP-клиенту.

• Операции записи (create_event, update_event, delete_event) доступны без этапа подтверждения. MCP-клиент (или инъекция промпта внутри него) может изменить данные вашего календаря.

• Вся связь происходит локально через stdio — никакие данные не отправляются на внешние сервисы.

• Чтобы сообщить об уязвимости, см. SECURITY.md.

Ограничения

• Только macOS (требуется EventKit и набор инструментов Swift)

• Требуется среда выполнения Bun

• Swift-бинарный файл компилируется один раз и вызывается синхронно для каждого вызова инструмента — не подходит для очень высокой пропускной способности

• Изменения повторяющихся событий применяются только к одному экземпляру (.thisEvent span)

• Доступ к календарю зависит от того, предоставила ли macOS TCC разрешение скомпилированному бинарному файлу

Устранение неполадок

"Calendar access is not granted" (Доступ к календарю не предоставлен)

Скомпилированный бинарный файл должен быть запущен хотя бы один раз из контекста, у которого есть TCC Календаря. Запустите сборку и тест:

bun run build
bin/calendar-reader list-events $(date +%Y-%m-%d)

Если это возвращает события, значит, у бинарного файла есть доступ к Календарю. Если нет, попробуйте запустить из Terminal.app (у которого обычно есть разрешение TCC Календаря).

События пусты

Проверьте, настроены ли у вас календари в Apple Calendar. Запустите:

bin/calendar-reader list-calendars

Ошибка компиляции

Убедитесь, что установлены Xcode Command Line Tools:

xcode-select --install

Лицензия

MIT