Apple Calendar MCP

Apple Calendar MCP предоставляет AI-клиенту удалённый доступ на чтение и запись к одному аккаунту iCloud Calendar. Он работает как TypeScript Worker без состояния на Cloudflare и не требует устройства Apple, чтобы оставаться в сети.

Одно развёртывание подключается к одному Apple Account. Это не многопользовательский календарный сервис.

Перед развёртыванием

Вам понадобятся:

• Аккаунт Cloudflare.

• Apple Account с двухфакторной аутентификацией.

• MCP-клиент, поддерживающий удалённые HTTPS-серверы и OAuth.

• Ваше название часового пояса IANA, например America/New_York.

Откройте страницы настройки Apple и Cloudflare самостоятельно. Агент может направлять вас и проверять результат, но не должен получать или вводить ваши пароли.

[!WARNING] Никогда не вставляйте пароль от Apple Account, пароль приложения Apple или пароль подтверждения в чат, систему контроля версий, журналы или issues.

Related MCP server: calendar-app-mcp

Создание пароля приложения Apple

1. Откройте account.apple.com и войдите.

2. Выберите Sign-In and Security > App-Specific Passwords.

3. Выберите Generate an app-specific password.

4. Дайте ему понятную метку, например Apple Calendar MCP.

5. Держите сгенерированное значение на странице Apple, пока Cloudflare не запросит его.

Apple требует двухфакторную аутентификацию для паролей приложений. У вас может быть до 25 активных паролей. Вы можете отозвать один или все. Смена или сброс основного пароля Apple Account отзывает все пароли приложений. См. инструкции Apple по паролям приложений.

[!WARNING] Пароль приложения Apple шире, чем разрешения Calendar, которые этот MCP показывает клиентам. Worker ограничивает себя только хостами iCloud CalDAV из списка разрешённых, но Apple не выдаёт пароль приложения только для Calendar.

Развёртывание в Cloudflare

1. Выберите Deploy to Cloudflare в верхней части этой страницы.

2. Войдите в Cloudflare и следуйте форме развёртывания.

3. Введите три секретных значения, когда Cloudflare запросит их:

   • ICLOUD_USERNAME: полный адрес электронной почты, используемый для вашего Apple Account и iCloud Calendar.

   • ICLOUD_APP_PASSWORD: пароль приложения, сгенерированный Apple. Сохраните его точно.

   • APPROVAL_PASSWORD: отдельный уникальный пароль, защищающий одобрение новых MCP-клиентов. Не используйте повторно ни один из паролей Apple.

4. Дождитесь завершения развёртывания Worker.

5. Откройте Workers & Pages, выберите Worker, затем выберите Settings и найдите Variables and Secrets.

6. Измените CALENDAR_TIME_ZONE с UTC на название вашего часового пояса IANA и разверните настройку.

7. Скопируйте конечную точку в таком виде: https://<worker-name>.<account-subdomain>.workers.dev/mcp.

Cloudflare хранит три секретных значения как зашифрованные секреты Worker. Форма развёртывания не записывает их в сгенерированный репозиторий или в локальный файл .dev.vars.

Если вы пропустили секрет или хотите заменить его, откройте Workers & Pages, выберите Worker, выберите Settings, найдите Variables and Secrets, добавьте или измените значение как Secret и выберите Deploy.

Cloudflare автоматически предоставляет пространство имён OAUTH_KV. Не добавляйте ID KV в wrangler.jsonc.

Подключение MCP-клиента

1. Добавьте развёрнутую конечную точку /mcp как пользовательский удалённый MCP-сервер или приложение.

2. Выберите Connect. Ваш клиент должен обнаружить OAuth и открыть страницу одобрения Apple Calendar MCP.

3. Подтвердите имя клиента и запрошенное разрешение.

4. Введите APPROVAL_PASSWORD и выберите Allow and return. Выберите Cancel, если страница запрашивает больше доступа, чем вы хотите.

5. Дождитесь, пока клиент сообщит о завершении подключения. Закройте вкладку браузера, если она осталась открытой после завершения.

6. Обновите или повторно просканируйте инструменты клиента. Клиенты могут кэшировать каталоги инструментов после подключения или обновления сервера.

Для Claude см. Использование пользовательских коннекторов с удалённым MCP. Для ChatGPT см. Режим разработчика и полные коннекторы MCP.

Страница одобрения предлагает два разрешения:

• Чтение календарей и событий предоставляет calendar:read и открывает семь инструментов чтения.

• Чтение и изменение календарей и событий предоставляет calendar:read calendar:write и добавляет четыре инструмента изменения.

Изменение разрешения требует повторной авторизации и обновления каталога инструментов. Обновление сервера не добавляет инструменты записи к существующему разрешению только на чтение.

[!WARNING] Действия записи, затрагивающие участников или приглашения, могут отправлять электронные письма или уведомления другим людям.

Проверка подключения

Сначала проверьте доступ на чтение:

1. Вызовите calendar_get_profile. Подтвердите идентификатор Apple Account и часовой пояс.

2. Вызовите calendar_list_calendars. Подтвердите, что ожидаемые названия календарей отображаются.

3. Если вы одобрили доступ только на чтение, убедитесь, что клиент не показывает инструменты изменения.

Развёртывание, ввод секретов, подключение OAuth и успешное чтение календаря — это отдельные состояния. Успешное чтение календаря доказывает, что учётные данные Apple работают.

Чтобы проверить доступ на запись, сначала создайте пустой временный календарь в Apple Calendar. Попросите агента выполнить этот ограниченный тест только после вашего подтверждения:

1. Создайте одно будущее событие с уникальным названием, без участников, без повторения и без напоминаний.

2. Прочитайте событие и сохраните его текущий ETag.

3. Измените только его название, используя этот ETag.

4. Прочитайте событие снова и используйте возвращённый ETag, чтобы удалить его.

5. Подтвердите, что событие отсутствует.

Если очистка не удалась, запишите точный календарь, название и время, чтобы вы могли удалить событие самостоятельно. Не тестируйте запись в календаре по умолчанию.

Вы также можете передать агенту ограниченную процедуру в Настройка Apple Calendar MCP с агентом.

Инструменты

Инструменты обновления, удаления и ответа на приглашения требуют последний ETag. Изменения повторяющихся вхождений также требуют исходный recurrenceId, возвращённый поиском.

Входные данные со временем используют метки времени RFC 3339 с Z или явным смещением. Клиенты могут опускать timeZone; при создании используется опубликованный часовой пояс IANA календаря, затем CALENDAR_TIME_ZONE. Выходные данные со временем включают значения UTC и локальные значения.

location — это видимое поле Calendar. structuredLocation может добавить название, адрес, широту, долготу и радиус. Подтверждённые координаты включают предпросмотр карты в Apple Calendar. Не угадывайте координаты.

description соответствует Notes в Calendar. url соответствует полю URL события. MCP сохраняет неподдерживаемые вложения и типы напоминаний при несвязанных изменениях, но не загружает, не скачивает и не изменяет вложения. Он не импортирует сырой ICS.

Использование собственного домена

Конечная точка workers.dev по умолчанию не требует настройки имени хоста. Собственный домен требует одного явного параметра в списке разрешённых:

1. Откройте Worker в Cloudflare.

2. Выберите Settings > Domains & Routes > Add > Custom Domain и добавьте имя хоста.

3. В разделе Variables and Secrets добавьте MCP_HOSTNAME как переменную в виде открытого текста. Введите только имя хоста, например calendar.example.com. Не включайте https://, путь, порт или учётные данные.

4. Разверните настройку.

5. Подключите клиентов снова по адресу https://<custom-host>/mcp и снова пройдите авторизацию.

Имя хоста является частью идентичности OAuth. Токены, выпущенные для workers.dev, не переносятся на собственный origin.

Добавление Cloudflare Access

Встроенный пароль подтверждения — это защита авторизации по умолчанию. Cloudflare Access — необязательная эшелонированная защита.

Если вы добавляете Access, защищайте только <hostname>/authorize. Оставьте /mcp, /.well-known/*, /oauth/token и /oauth/register доступными для MCP-клиентов. После того как вы убедитесь, что Access защищает /authorize, добавьте EXTERNAL_AUTHORIZATION=true как переменную Worker в виде открытого текста.

[!WARNING] Устанавливайте EXTERNAL_AUTHORIZATION=true только после того, как внешняя защита охраняет /authorize. Эта настройка объявляет, что внешняя защита активна.

Безопасность

Worker получает ваше имя пользователя Apple и пароль приложения во время выполнения. Вы доверяете своему аккаунту Cloudflare, развёрнутому исходному коду, Apple и каждому подключённому MCP-клиенту. Ограничьте доступ к своему аккаунту Cloudflare и подключайте только те клиенты, которым доверяете.

APPROVAL_PASSWORD защищает новые одобрения. Маршрут одобрения закрыт по умолчанию, если этот пароль не настроен или EXTERNAL_AUTHORIZATION не объявляет проверенную внешнюю защиту. Любой, кто пройдёт защиту, может авторизовать клиента для настроенного Apple Account.

[!WARNING] Смена APPROVAL_PASSWORD не отзывает уже выпущенные токены OAuth.

Провайдер OAuth Cloudflare хранит токены доступа, токены обновления, коды авторизации и секреты зарегистрированных клиентов в виде хеша. Он шифрует свойства авторизации. Имена клиентов и метаданные разрешений остаются видимыми в хранилище, поэтому они не должны содержать секреты. См. документацию провайдера по хранилищу KV и очистке.

Worker отправляет учётные данные Apple только через HTTPS на хосты iCloud CalDAV из списка разрешённых. Аргументы инструментов не могут выбирать вышестоящий хост. В ошибках скрываются значения, похожие на учётные данные. Worker не записывает в журнал аргументы инструментов или данные событий.

Результаты инструментов могут включать названия, заметки, места, участников и URL. MCP-клиенты могут сохранять эти данные в соответствии с собственными политиками продукта и рабочей области.

Доступ на запись охватывает создание событий, изменения, удаление и ответы на приглашения. ETag предотвращают перезапись более нового события, но не могут сделать непреднамеренную запись безвредной. Несвязанные обновления сохраняют неподдерживаемые свойства Apple, когда это возможно.

Развёртывайте из этого канонического репозитория или из форка, изменения которого вы проверили. Удалённый MCP-сервер может изменить свой каталог инструментов, когда его владелец развёртывает новый код.

Отзыв или смена доступа

Если вы подозреваете компрометацию, сначала отзовите старый пароль приложения Apple. Затем замените его и проверьте доступ. Это вызывает кратковременный простой.

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

• Ошибка 401 или отклонение пароля iCloud обычно означает, что пароль приложения отсутствует или отозван. Создайте или замените его в Apple и Cloudflare. Не вставляйте его в чат.

• Отсутствие инструментов записи обычно означает, что у клиента разрешение только на чтение или кэшированный каталог инструментов. Обновите инструменты, затем отключитесь и авторизуйтесь снова, если нужно.

• Пользовательский домен, который отклоняет запросы к /mcp, обычно имеет отсутствующий или недействительный MCP_HOSTNAME. Укажите точное имя хоста и выполните повторный деплой.

• Страница подтверждения, которая при сбое отказывает в доступе, не имеет ни APPROVAL_PASSWORD, ни объявленного внешнего защитного механизма. Добавьте секрет подтверждения, если вы ещё не проверили Cloudflare Access на /authorize.

Локальная разработка

bun install
cp .dev.vars.example .dev.vars
bun run test
bun run typecheck
bun run cloudflare:check

Храните .dev.vars локально. Выполняйте деплой с помощью bun run deploy.

Лицензия

MIT