Apple Calendar MCP

Apple Calendar MCP — это локальный сервер Model Context Protocol для безопасного подключения ИИ-ассистентов к Apple Calendar на macOS.

Он использует TypeScript MCP-сервер, Swift EventKit-хелпер, локальное состояние SQLite и нативное macOS-приложение для настройки. Данные календаря остаются на Mac, пользователи выбирают, какие календари видны, а операции записи защищены режимами разрешений, шлюзами подтверждения, проверками дубликатов, идемпотентностью, записями отката, журналами аудита и лентами изменений.

Ключевые возможности

• Чтение календарей, событий, доступности и разрешений Apple Calendar через MCP-инструменты.

• Создание, обновление, перенос и удаление событий с предпросмотром и подтверждением по умолчанию.

• Серверное применение списков разрешённых календарей, чтобы заблокированные календари оставались скрытыми от агентов.

• Отслеживание записей отката, записей аудита, компактных снимков и эффективных по токенам лент изменений.

• Генерация конфигураций клиентов для Claude Desktop, Codex, Cursor, OpenClaw и универсальных MCP-клиентов.

• Встроенный мастер настройки для macOS: разрешения календаря, списки разрешённых, режим прав, генерация конфигурации и проверка.

Related MCP server: nucleus-apple-mcp

Архитектура

flowchart TD
  A["MCP Client<br/>Claude, Codex, Cursor, OpenClaw"] --> B["TypeScript MCP Server"]
  B --> C["Calendar Service Layer"]
  C --> D["Swift EventKit Helper"]
  D --> E["Apple Calendar / EventKit"]
  C --> F["SQLite Local State"]
  F --> G["Config, Audit, Rollback,<br/>Snapshots, Change Feed,<br/>Idempotency"]
  H["Native macOS Setup App"] --> D
  H --> F

MCP-сервер общается через stdio. Логи записываются в stderr или в необязательный локальный файл лога, но никогда в stdout, чтобы трафик протокола MCP оставался чистым.

Требования

• macOS с доступом к Apple Calendar и EventKit.

• Node.js >=22.5.

• Инструменты Swift через Xcode Command Line Tools или Xcode.

• MCP-клиент, такой как Claude Desktop, Codex, Cursor, OpenClaw или другой совместимый со stdio клиент.

Установка из исходников

git clone <repo-url>
cd apple-calendar-mcp
npm install
npm run build
npm run helper:bundle
npm run helper:setup

Приложение настройки проводит через:

1. Объяснение и запрос разрешения на календарь.

2. Выбор списка разрешённых календарей.

3. Выбор режима прав.

4. Генерацию конфигурации MCP-клиента.

5. Проверки и тестовое подключение.

Сгенерированная локальная конфигурация хранится в:

~/Library/Application Support/AppleCalendarMCP/

Настройка MCP-клиента

Сгенерируйте проверенные конфигурации клиентов:

npm run client-configs:generate

Скопируйте или объедините сгенерированный файл из .generated/client-configs/ в ваш клиент:

• Claude Desktop: claude_desktop_config.json

• Codex: добавьте codex.config.toml в ~/.codex/config.toml

• Cursor: скопируйте или объедините cursor.mcp.json в ~/.cursor/mcp.json или в проектный .cursor/mcp.json

• OpenClaw: объедините openclaw.openclaw.json в ~/.openclaw/openclaw.json

• Универсальные MCP-клиенты: используйте generic-mcp-client.json

Проверьте после копирования:

npm run client-configs:validate
npm run client-configs:diagnose

Сгенерированные конфигурации используют абсолютный путь к исполняемому файлу Node, абсолютную точку входа MCP-сервера и блок env. Команда и аргументы никогда не объединяются в строку оболочки, что исключает сбои при путях с пробелами.

Путь запуска через npx

Публикуемый пакет сервера предоставляет этот бинарник:

npx apple-calendar-mcp

Для локальной разработки и кандидатов на релиз предпочтительнее:

npm run start:mcp

Перед публикацией в npm опубликуйте внутренние пакеты рабочего пространства в порядке зависимостей или используйте артефакты релиза, созданные через npm run release:package.

Модель безопасности

Apple Calendar MCP спроектирован вокруг многоуровневой защиты:

• Разрешение на календарь macOS требуется до доступа к EventKit.

• Списки разрешённых календарей ограничивают, какие календари могут видеть агенты.

• Режимы «только чтение», «спрашивать перед записью», «доверенная запись» и «полная запись» контролируют риск записи.

• MVP-записи требуют явного подтверждения или потока предпросмотра с подтверждением.

• Деструктивные и неоднозначные операции возвращают семантические ошибки вместо догадок.

• Записи повторяющихся событий требуют явной области действия.

• Содержимое календаря рассматривается как недоверенный ввод.

• Записи аудита, записи отката, ключи идемпотентности и ленты изменений записываются локально.

Полная модель безопасности описана в docs/Security Specification.md.

Скриншоты

Заглушки скриншотов релиза:

• Приветствие мастера настройки и шаг разрешения на календарь.

• Шаг списка разрешённых календарей и режима прав.

• Шаг конфигурации клиента и проверки.

• Экран настроек и диагностики.

Сделайте скриншоты подписанного релиза перед публичным распространением.

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

• Отказ в доступе к календарю: откройте «Системные настройки» > «Конфиденциальность и безопасность» > «Календари» и включите вспомогательное приложение.

• MCP-сервер не запускается (красный в настройке): выполните npm run build и убедитесь, что packages/mcp-server/dist/index.js существует.

• Cursor или Codex не подключаются: перегенерируйте конфигурации через npm run client-configs:generate и убедитесь, что скопированная конфигурация использует абсолютные пути.

• Клиент видит сервер, но не видит инструменты: перезапустите MCP-клиент после изменений конфигурации, затем выполните npm run client-configs:diagnose.

• Разделение stdout/stderr не работает: удалите любой вывод в stdout из пути MCP-сервера; логи должны идти в stderr.

• Большие чтения не работают: используйте более узкие диапазоны дат. Сервис чтения внутренне разбивает большие окна на части, но очень большие запросы EventKit могут всё равно требовать повтора.

Разработка

npm install
npm run build
npm test
npm run helper:bundle
npm run helper:setup

Полезные команды:

• npm run typecheck

• npm run client-configs:generate

• npm run client-configs:validate

• npm run release:verify

• npm run release:package

Прочитайте docs/Development Guide.md перед внесением изменений, связанных с безопасностью.

Структура репозитория

apps/macos-helper/        Swift EventKit bridge and native setup app
packages/mcp-server/      MCP stdio server and tool registration
packages/calendar-service/Business logic for reads, writes, rollback, snapshots
packages/sqlite-store/    Local SQLite persistence and migrations
packages/shared/          Shared schemas and typed contracts
scripts/                  Helper, config, diagnostics, and release scripts
tests/                    Phase-based safety and behavior tests
docs/                     Consolidated maintainer and release documentation

Релиз

Создайте воспроизводимые локальные артефакты релиза:

npm run release:package

Артефакты и контрольные суммы записываются в:

dist/release/

Рабочий процесс релиза GitHub запускает тот же скрипт пакета при пушах тегов, соответствующих v*.

Дорожная карта

• Подписанная и нотариально заверенная упаковка релиза для macOS.

• Публичный процесс публикации в npm после подтверждения пространства имён пакета.

• Больше сквозных смоук-тестов клиентов для поддерживаемых MCP-клиентов.

• Расширенные бенчмарки пагинации снимков/лент изменений.

• Улучшенный захват скриншотов в приложении и публичные документационные материалы.

Участие

Безопасность, надёжность, доверие пользователей, соответствие MCP и поддерживаемость важнее удобства. Держите изменения в рамках, запускайте полный набор тестов и обновляйте документацию при изменении поведения. Не обходите проверки прав, списки разрешённых, шлюзы подтверждения, записи отката, записи аудита, проверки идемпотентности или семантические ошибки.

Начните с:

• docs/Product Specification.md

• docs/Technical Specification.md

• docs/Security Specification.md

• docs/Development Guide.md

• docs/Installation Guide.md

• docs/Release Checklist.md