icloud-calendar-mcp

Надежный, легковесный MCP-сервер для Apple iCloud Calendar. Нативный TypeScript/Node.js, прямое подключение к iCloud через CalDAV; не требует Java, Python, Go, AppleScript, macOS или Calendar.app.

English summary: A production-oriented, cross-platform TypeScript MCP server for Apple iCloud Calendar. It provides guarded CalDAV CRUD, persistent opaque handles, idempotent writes, ETag concurrency control, recurrence expansion, stdio and secured Streamable HTTP transports.

Установка

Требуется Node.js 20 или новее. Необходимо использовать «пароль приложения» Apple, не используйте основной пароль учетной записи Apple.

npx icloud-calendar-mcp

Создание пароля приложения: войдите в account.apple.com, перейдите в «Вход и безопасность» → «Пароли приложений». Apple может ограничивать количество одновременно активных паролей приложений; после отзыва пароля этот сервис получит AUTH_FAILED.

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

{
  "mcpServers": {
    "icloud-calendar": {
      "command": "npx",
      "args": ["-y", "icloud-calendar-mcp"],
      "env": {
        "ICLOUD_USERNAME": "you@example.com",
        "ICLOUD_APP_PASSWORD": "xxxx-xxxx-xxxx-xxxx"
      }
    }
  }
}

stdout используется только для JSON-RPC; все журналы записываются в stderr.

Related MCP server: Chronos MCP

Инструменты и содержимое MCP

Инструменты одновременно возвращают structuredContent и текстовый JSON, а также объявляют аннотации read-only/destructive/idempotent/open-world. Ресурсы: calendar://calendars. Явные шаблоны prompts для пользователя: schedule_event, reschedule_event, find_conflicts; они не принимают решений о расписании за пользователя.

События поддерживают: временные/целодневные, заголовок, описание, место, URL, RRULE, DISPLAY alarm и участников. Поле участников ограничено правами iCloud и общим доступом к календарю; этот сервис не будет ошибочно сообщать, что «запись ATTENDEE» означает успешную отправку приглашения.

Семантика времени и повторяющихся событий

• Для временных событий на входе необходимо указывать время в формате ISO 8601 и IANA timezone; на выходе также явно возвращается часовой пояс.

• Для целодневных событий start/end используют YYYY-MM-DD, end не включается в событие. Например, целодневное событие 18 августа: start=2026-08-18, end=2026-08-19.

• iCalendar строится и разбирается с помощью ical.js, без конкатенации строк с пользовательскими полями; тесты покрывают DST, UTC и границы целодневных событий.

• list_events запрашивает развертывание occurrence RRULE через CalDAV calendar-data/expand.

• whole_series поддерживается для обновления/удаления. single_occurrence, this_and_future возвращают UNSUPPORTED_OPERATION при непроверенной возможности iCloud обрабатывать исключения recurrence, никогда не изменяя молча всю серию.

Режим HTTP

HTTP по умолчанию отключен. При включении прослушивает только loopback, а bearer token должен быть не менее 24 символов:

ICLOUD_MCP_TRANSPORT=http \
ICLOUD_MCP_HTTP_TOKEN='replace-with-a-long-random-token' \
ICLOUD_MCP_HTTP_PORT=3000 \
npx icloud-calendar-mcp

• MCP endpoint: POST /mcp

• Проверка работоспособности: GET /healthz (не обращается к Apple и не раскрывает статус учетной записи)

• Обязательный bearer token; фиксированный allowlist хостов; Origin по умолчанию все запрещены; лимит запроса по умолчанию 1 МиБ; локальное ограничение скорости чтения/записи; тайм-аут и границы безопасных заголовков ответа.

• Установите стабильные параметры через ICLOUD_MCP_CONFIG=/absolute/path/config.json, например allowedHosts, allowedOrigins, timeoutMs, maxEvents, ограничения скорости чтения/записи и лимит запроса. Учетные данные не должны помещаться в этот файл.

Полный контракт конфигурации см. в docs/tool-contracts.md, модель безопасности — в docs/security.md.

Надежность

• UID для create является стабильным производным SHA-256 от request_id; повторные запросы не создадут второе событие.

• create использует If-None-Match: *, update/delete используют If-Match с прочитанным ETag.

• Журнал записывается с атомарным rename в каталог пользовательских данных (по умолчанию ~/.icloud-caldav-mcp/journal.json, с ужесточенными правами), сохраняя replay запросов и opaque handle.

• Для временных сбоев 429/5xx/сеть применяется экспоненциальная задержка с джиттером и уважается Retry-After; при отсутствии ETag в ответе выполняется опрос видимости read-after-write.

• Стабильные коды ошибок: AUTH_FAILED, CALENDAR_NOT_FOUND, EVENT_NOT_FOUND, ETAG_CONFLICT, INVALID_EVENT, RATE_LIMITED, TEMPORARY_UNAVAILABLE, UNSUPPORTED_OPERATION.

Разработка и smoke-тест с реальной учетной записью

pnpm install
pnpm check
pnpm pack

Изменения, затрагивающие пользователей, фиксируются с помощью pnpm changeset. После отправки в main Changesets автоматически создает или обновляет Release PR; после слияния этого PR происходит автоматическая публикация через npm Trusted Publishing с provenance. Перед первым включением необходимо настроить .github/workflows/release.yml как Trusted Publisher в настройках пакета npm.

CI использует fake adapter/HTTP fixtures, не требует реальной учетной записи Apple. Опциональное реальное тестирование выполняется только локально при явном указании ICLOUD_USERNAME и ICLOUD_APP_PASSWORD: pnpm smoke:icloud. Текущий smoke-набор по умолчанию пропускает операции записи; для первой реальной проверки рекомендуется вручную проверить поведение discovery/list/create/update/delete/recurrence exception на специальном тестовом календаре.

Устранение неполадок: 401/403 — проверьте пароль приложения; 412 — конфликт ETag, повторно выполните list_events/get_event; 429 — повторите после ожидания; неизвестный handle — журнал удален или изменен каталог данных. Не вставляйте полный URL CalDAV, Authorization или тело события в issue.

Лицензия

MIT. Реализация является независимым оригинальным кодом; публичный проект используется только для исследования различий в интерфейсах и архитектуре, без копирования исходного кода третьих сторон.