Apple-Tools-MCP

Единый MCP-сервер для приложений Apple на macOS.

Одна точка входа для Mail, Calendar, Reminders, Messages, Contacts, Notes, Shortcuts, Files, System и Maps. Этот сервер оборачивает отдельные серверы и предоставляет единый интерфейс MCP.

Что он делает

Читает контекст из нескольких приложений Apple
Единые действия для всех приложений
Промпты для планирования дня, сортировки коммуникаций и подготовки к встречам
Постоянные значения по умолчанию для почты, календаря, напоминаний, заметок и маршрутизации коммуникаций
Предпочтения для отдельных контактов для людей, которые всегда предпочитают определённый способ связи
Вспомогательные рабочие процессы для маршрутизации коммуникаций, архивирования почты, фиксации последующих действий и сводок по совместной работе
Помощники для цепочек Mail и редактирование методов Contacts в одном месте
Предпросмотр, аудит и отмена для обратимых действий
Рабочие процессы с вложениями и документами с учётом Files в пределах заданных корневых каталогов
Рабочие процессы с учётом System, использующие активное приложение, буфер обмена, уведомления, запущенные приложения и релевантные для ассистента настройки macOS
Достоверный контекст Focus и объединённые системные снимки для брифинга и маршрутизации
Явная запись настроек macOS для внешнего вида, Finder, Dock и ключевых настроек Accessibility
Ограниченные резервные GUI-инструменты, когда нативный MCP предметной области приложения не может напрямую выполнить задачу
Рабочие процессы с файлами с учётом Finder, теги Finder, недавние местоположения и учёт iCloud Drive через Apple Files
Рабочие процессы с учётом поездок, использующие Apple Maps для поиска мест и оценки маршрутов
Инструменты ежедневного брифинга, еженедельного брифинга и сортировки коммуникаций
Резервный доступ к промптам через apple_list_prompts и apple_get_prompt
Одна цель установки вместо десяти отдельных конфигураций

Когда использовать

Рабочие процессы персонального ассистента для нескольких приложений Apple
Межприложенческие операции (например, Calendar и Reminders вместе)
Более простая настройка без отдельного подключения каждого автономного MCP

Обнаружение инструментов

Apple-Tools-MCP предоставляет полный набор инструментов через tools/list, с аннотациями readOnlyHint/destructiveHint и схемами структурированного вывода — современные клиенты сами отложенно загружают большие наборы инструментов. Для клиентов с ограниченным контекстом:

search_tools находит инструменты по имени, псевдонимам и тегам предметной области
get_tool_info загружает полную схему и примеры для одного инструмента по запросу
сгенерированные обёртки режима кода экспортируются в generated/tool_wrappers/python

Установка на этом Mac

Быстрый старт (uvx, из PyPI)

Если установлен uv:

uvx apple-tools-mcp

Без клонирования и управления venv.

Из клона

git clone https://github.com/JonathanRReed/Apple-MCPs.git
cd Apple-MCPs
uv sync --all-packages

Это создаёт единое рабочее пространство uv с унифицированной точкой входа в .venv/bin/apple-tools-mcp и консольным скриптом каждого автономного сервера (bash scripts/install_all.sh делает то же самое с резервным вариантом через venv для машин без uv). Также можно указать MCP-клиенту на Apple-Tools-MCP/start.sh, который предпочитает uv run и переходит к обычной начальной настройке venv (требуется Python 3.11+).

Установка в AI-агентах

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

{
  "mcpServers": {
    "apple-tools": {
      "command": "uvx",
      "args": ["apple-tools-mcp"],
      "env": {
        "APPLE_MAIL_MCP_SAFETY_PROFILE": "full_access",
        "APPLE_CALENDAR_MCP_SAFETY_MODE": "safe_manage",
        "APPLE_REMINDERS_MCP_SAFETY_MODE": "safe_manage",
        "APPLE_FILES_MCP_ALLOWED_ROOTS": "/Users/you/Desktop,/Users/you/Documents,/Users/you/Downloads,/Users/you/Library/Mobile Documents/com~apple~CloudDocs",
        "APPLE_FILES_MCP_SAFETY_MODE": "safe_manage",
        "APPLE_SYSTEM_MCP_SAFETY_MODE": "safe_manage",
        "APPLE_CONTACTS_MCP_SAFETY_MODE": "safe_manage",
        "APPLE_NOTES_MCP_SAFETY_MODE": "full_access",
        "APPLE_MESSAGES_MCP_SAFETY_MODE": "full_access",
        "APPLE_SHORTCUTS_MCP_SAFETY_MODE": "full_access"
      }
    }
  }
}

Запускаете из клона? Используйте /path/to/Apple-MCPs/Apple-Tools-MCP/start.sh как команду с пустым args.

Пример для Claude Code

claude mcp add --transport stdio --scope project apple-tools -- uvx apple-tools-mcp

Что он предоставляет

Инструменты проверки работоспособности и обзора для всех приложений
Промпты для нескольких приложений
Делегированные инструменты из Mail, Calendar, Reminders, Messages, Contacts, Notes, Shortcuts, Files, System и Maps
Подсказки и руководства по разрешениям
Ресурсы и промпты для Files, System и Maps
Унифицированные обёртки для Focus, системного контекста, показа в Finder, открытия файлов и добавления тегов к файлам
Инструменты предпочтений: получение, определение и обновление значений по умолчанию и предпочтений контактов
Инструменты коммуникации: подготовка, отправка, предпросмотр
Инструменты рабочих процессов: архивирование, создание напоминаний и заметок со значениями по умолчанию, предпросмотр таких записей со значениями по умолчанию, фиксация последующих действий, предпросмотр фиксации последующих действий и суммирование совместной работы по событию
Инструменты повышения надёжности запуска: строгие обёртки Maps, обнаружение дубликатов контактов, помощники для папок дайджестов и маршрутизация через мост Shortcut
Инструменты аудита: список недавних действий и отмена
Инструменты брифинга: ежедневный, еженедельный и сортировка коммуникаций
Резервный доступ к промптам: apple_list_prompts и apple_get_prompt
Инструменты цепочек Mail: получение, ответ, архивирование
Изменение контактов: создание, обновление, удаление с помеченными методами
Диагностика разрешений Calendar и Messages
Запуск и восстановление: apple_health, apple_permission_guide, apple_recheck_permissions

Значения по умолчанию ассистента

Apple-Tools-MCP может сохранять облегчённый файл состояния ассистента со значениями по умолчанию для:

учётной записи почты по умолчанию
архивного почтового ящика по умолчанию
календаря по умолчанию
списка напоминаний по умолчанию
папки заметок по умолчанию
предпочитаемого канала связи: messages, mail или auto
предпочитаемого типа цели для сообщений: phone, email или auto
переопределений предпочитаемого канала и цели для отдельных контактов

Определяйте и сохраняйте разумные значения по умолчанию с помощью apple_detect_defaults, просматривайте их с помощью apple_get_preferences и переопределяйте с помощью apple_update_preferences.

По умолчанию файл состояния хранится в ~/.apple-tools-mcp/preferences.json. Переопределите его с помощью APPLE_AGENT_MCP_STATE_FILE.

Apple-Tools-MCP также сохраняет недавние действия ассистента в ~/.apple-tools-mcp/actions.json, чтобы единый сервер мог предоставлять историю аудита и отмену для обратимых операций.

Как с ним работать

Сначала находите людей через Contacts, затем выбирайте между Messages и Mail на основе сохранённых значений по умолчанию.
Задавайте предпочтения для отдельных контактов, если человек всегда предпочитает определённый канал.
Предварительно просматривайте рискованные действия и потоки создания со значениями по умолчанию, когда клиент хочет подтверждения.
Используйте помощники для цепочек Mail, когда пользователь имеет в виду переписку, а не одно сообщение.
Задавайте значения по умолчанию заранее (архивный почтовый ящик, календарь, список напоминаний, папка заметок), чтобы ассистент не переспрашивал.
Поддерживайте информацию о контактах в актуальном состоянии, чтобы маршрутизация коммуникаций работала надёжно.
Используйте Files перед Mail, Messages, Notes или Shortcuts, когда запрос связан с локальными документами.
Проверяйте системный контекст перед прерывающими действиями, особенно когда важны активное приложение, буфер обмена или состояние батареи.
Рассматривайте поддержку Focus как достоверную реализацию по мере возможностей. Используйте её, когда она доступна, и не придумывайте текущий режим Focus, если MCP сообщает, что он не поддерживается в локальной конфигурации.
Используйте apple_update_system_setting для изменения настроек macOS и apple_control_frontmost_app только когда нативный инструмент предметной области приложения не может выполнить задачу.
Предпочитайте явные инструменты системных настроек общей GUI-автоматизации, когда запрос на самом деле является изменением настроек macOS.
Используйте резервные GUI-инструменты только когда нативный MCP предметной области не может выполнить задачу и клиент предоставил доступ к Accessibility.
Используйте нативные MCP-инструменты Maps для поиска по картам и маршрутов. Не подменяйте их shell, веб- или внешними картографическими провайдерами при проверке поддерживаемого поведения Maps.
Используйте Shortcuts как явный мост, когда отсутствует нативная поддержка предметной области, вместо самодельных shell- или GUI-решений.
Используйте специальные помощники для папок дайджестов перед сохранением ежедневных или еженедельных брифингов в Notes.
Используйте Maps, когда маршрутизация или время в пути влияют на планирование или коммуникацию.
Используйте apple_list_recent_actions и apple_undo_action для обратимых операций.
Когда Mail должен использовать конкретную личность отправителя, передавайте точный email отправителя в from_account, а не только псевдоним учётной записи.

Разрешения macOS

Mail требует доступа к автоматизации (Automation) приложения Mail
Calendar требует доступа к Calendar
Reminders требует доступа к Reminders
Messages требует доступа к автоматизации для Messages, а также Full Disk Access для работы с историей
Contacts требует доступа к Contacts
Notes требует доступа к автоматизации для Notes
Shortcuts обычно работает без отдельного запроса на доступ к конфиденциальным данным
Доступ к Files регулируется переменной APPLE_FILES_MCP_ALLOWED_ROOTS, а не запросом конфиденциальности macOS
Системные действия могут вызывать запросы System Events, Accessibility или автоматизации — в зависимости от хост-приложения
Статус Focus определяется по принципу best-effort и выдаёт достоверные данные на неподписанных локальных установках
История Notification Center не декларируется как доступная там, где macOS не предоставляет к ней корректный доступ
Maps не требует запроса на доступ к данным, однако поиск и построение маршрутов требуют компиляции локального Swift-хелпера

Чек-лист запуска

Добавьте uvx apple-tools-mcp (или entrypoint из клона репозитория — Apple-Tools-MCP/start.sh либо установленный .venv/bin/apple-tools-mcp) в конфигурацию вашего MCP-клиента
Перезагрузите или переподключите клиент, чтобы набор инструментов Apple-Tools-MCP загрузился в контекст
Сначала вызовите apple_health, чтобы проверить работоспособность всех доменов
Если какой-то домен заблокирован, вызовите apple_permission_guide
После изменения разрешений macOS вызовите apple_recheck_permissions

Транспорты и проверка протокола

stdio — транспорт по умолчанию и рекомендуемый вариант. Чтобы вместо него развернуть сервер по Streamable HTTP, задайте APPLE_AGENT_MCP_TRANSPORT=streamable-http (опционально — APPLE_AGENT_MCP_HOST и APPLE_AGENT_MCP_PORT); именно этот режим используется ниже для проверки протокола.

Официальная проверка соответствия MCP

Запустите Apple-Tools-MCP в режиме conformance:

cd /path/to/Apple-MCPs/Apple-Tools-MCP
APPLE_AGENT_MCP_TRANSPORT=streamable-http \
APPLE_AGENT_MCP_PORT=8765 \
APPLE_AGENT_MCP_CONFORMANCE_MODE=1 \
./start.sh

Затем выполните официальный активный набор тестов:

npx -y @modelcontextprotocol/conformance server \
  --url http://127.0.0.1:8765/mcp \
  --suite active

APPLE_AGENT_MCP_CONFORMANCE_MODE=1 добавляет опциональную conformance-поверхность MCP, охватывающую типы контента, ресурсы, шаблоны ресурсов, промпты, прогресс и автодополнение (фикстуры для возможностей, удалённых спецификацией 2026-07-28, намеренно отсутствуют). Этот режим предназначен для CI и тестирования протокола, а не для повседневной работы ассистента.

Инструменты брифинга и триажа (apple_generate_daily_briefing, apple_generate_weekly_briefing, apple_triage_communications_task) являются стандартными синхронными инструментами: экспериментальный MCP tasks API, который они использовали ранее, был удалён из спецификации (SEP-1686) и SDK — имена инструментов и результаты при этом не изменились.

Документация по запуску

Быстрая проверка через Inspector CLI

Находясь в каталоге этого сервера, выполните:

npx -y @modelcontextprotocol/inspector --cli bash ./start.sh --method tools/list
npx -y @modelcontextprotocol/inspector --cli bash ./start.sh --method prompts/list
npx -y @modelcontextprotocol/inspector --cli bash ./start.sh --method resources/list

Для полной проверки всего репозитория запустите:

cd /path/to/Apple-MCPs
bash scripts/inspector_smoke.sh

Промпт маршрутизации для агента

tools/list возвращает полный набор инструментов. Если контекст ограничен, сначала используйте search_tools, а затем get_tool_info — и только для тех инструментов, которые планируете вызывать.

Resolve recipient via Contacts first. Confirm if multiple matches.
Omit service_name parameter entirely.

Run before any iMessage or Mail action.

Search requires a query string (sender, subject, or "*" as wildcard). No list-all endpoint.
If text vs. email is ambiguous, ask once.

Confirm date, time, duration, and title before writing.

Reminders are organized into lists. Identify available lists on first use and set a default.
due_date requires timezone offset: yyyy-MM-ddTHH:mm:ss-HH:00

Multiple accounts may have a "Notes" folder. Identify them on first use and set a default.
Use for reference only. Time-sensitive items go to Reminders or Calendar.

List available shortcuts before running if request is vague.

Use Files before Mail, Messages, Notes, or Shortcuts when the request references local paths or attachments.
Confirm the exact path before mutation or send actions.

Use System when local desktop context affects the next action.
Keep writes scoped unless the user clearly asked for a notification, clipboard update, or app launch.

Use Maps when place lookup or travel time affects scheduling or communication.
Confirm origin, destination, and transport mode for time-sensitive plans.

Has due date/time -> Reminders
Reference material, no action -> Notes
Involves another person -> iMessage or Mail (Contacts first)
Text vs. email unclear -> ask once

service_name on iMessage calls causes error (-1728). Omit it.
Bare timestamps without timezone offset fail on Reminders.
Mail has no "list recent" endpoint. Always pass a search query.
Use search_tools plus get_tool_info to inspect tools without loading every schema into context.
Multiple Notes folders exist across accounts. Pick one default.
Files access is limited to APPLE_FILES_MCP_ALLOWED_ROOTS.
Some System actions depend on host app automation approval.
Maps search and directions depend on the local Swift helper and Xcode command line tools.

<apple_tools>
`tools/list` returns the full tool surface. If context is constrained, use `search_tools` first, then `get_tool_info` only for the tools you plan to call.

<routing>
  <imessage trigger="text, message, msg, iMessage">
    Resolve recipient via Contacts first. Confirm if multiple matches.
    Omit service_name parameter entirely.
  </imessage>

  <contacts trigger="lookup, phone number, email, contact">
    Run before any iMessage or Mail action.
  </contacts>

  <mail trigger="email, mail, inbox, draft, reply">
    Search requires a query string (sender, subject, or "*" as wildcard). No list-all endpoint.
    If text vs. email is ambiguous, ask once.
  </mail>

  <calendar trigger="calendar, event, schedule, appointment, meeting, block time">
    Confirm date, time, duration, and title before writing.
  </calendar>

  <reminders trigger="remind me, task, to-do, don't forget">
    Reminders are organized into lists. Identify available lists on first use and set a default.
    due_date requires timezone offset: yyyy-MM-ddTHH:mm:ss-HH:00
  </reminders>

  <notes trigger="note, jot down, write this down, save this">
    Multiple accounts may have a "Notes" folder. Identify them on first use and set a default.
    Use for reference only. Time-sensitive items go to Reminders or Calendar.
  </notes>

  <shortcuts trigger="shortcut, automation, run shortcut">
    List available shortcuts before running if request is vague.
  </shortcuts>

  <files trigger="file, folder, attachment, document, download, desktop">
    Use Files before Mail, Messages, Notes, or Shortcuts when the request references local paths or attachments.
    Confirm the exact path before mutation or send actions.
  </files>

  <system trigger="clipboard, frontmost app, battery, notification, open app">
    Use System when local desktop context affects the next action.
    Keep writes scoped unless the user clearly asked for a notification, clipboard update, or app launch.
  </system>

  <maps trigger="map, directions, route, commute, eta, address, place">
    Use Maps when place lookup or travel time affects scheduling or communication.
    Confirm origin, destination, and transport mode for time-sensitive plans.
  </maps>
</routing>

<disambiguation>
  1. Has due date/time -> Reminders
  2. Reference material, no action -> Notes
  3. Involves another person -> iMessage or Mail (Contacts first)
  4. Text vs. email unclear -> ask once
</disambiguation>

<known_gotchas>
  - service_name on iMessage calls causes error (-1728). Omit it.
  - Bare timestamps without timezone offset fail on Reminders.
  - Mail has no "list recent" endpoint. Always pass a search query.
  - Use `search_tools` plus `get_tool_info` to inspect tools without loading every schema into context.
  - Multiple Notes folders exist across accounts. Pick one default.
  - Files access is limited to APPLE_FILES_MCP_ALLOWED_ROOTS.
  - Some System actions depend on host app automation approval.
  - Maps search and directions depend on the local Swift helper and Xcode command line tools.
</known_gotchas>
</apple_tools>

Связанные серверы

Вложения в письмах

Прежде чем прикреплять локальные файлы к черновику или исходящему письму, задайте для переменной APPLE_MAIL_MCP_ALLOWED_ATTACHMENT_ROOT путь к выделенному каталогу. Если переменная не задана, работа с вложениями отключена. То же ограничение на каталог действует и для отдельного сервера Mail, и для объединённого сервера Apple Tools.