macos-mcp

Управляйте Reminders, Calendar, Notes, Mail, Messages и Contacts на macOS из ИИ-агента или из командной строки.

Apple предоставляет три поверхности автоматизации для этих приложений, и каждая из них где-то даёт сбой. EventKit не охватывает Notes, Mail, Messages и Contacts. Чтение Messages через JXA ничего не возвращает на Sonoma и новее. Чтение Mail через JXA истекает по тайм-ауту через 60 секунд на реальном почтовом ящике. Этот проект использует мост, который работает для каждого приложения, и объясняет почему в DECISION.md.

Требуется Mac. Эти мосты — EventKit, Apple Events и чтение SQLite из локальных баз данных Apple. Нет сборки для Linux, Windows, iOS, Android или браузера.

Три способа использования

Как MCP-сервер. Локальный stdio-транспорт, работает с любым MCP-совместимым клиентом на том же Mac (Claude Code, Claude Desktop, Cursor, Zed, Continue, ChatGPT desktop). Восемь инструментов, перечисленных в разделе Инструменты.

Как навык агента. Те же мосты вызываются как shell-команды, без загрузки схем инструментов в контекст. MCP-сервер помещает все восемь определений инструментов перед моделью в начале сессии, независимо от того, касается ли сессия приложений Mac; навык — это одна строка описания, пока что-то его не активирует. См. skills/macos/ для навыка и docs/mcp-vs-skill.md о том, как выбрать.

Как CLI. EventKitCLI — это отдельный Swift-бинарник, который выводит JSON в stdout. Рецепты JXA и SQLite из навыка работают везде, где есть shell.

Related MCP server: Apple MCP

Быстрый старт

Установка как плагин Claude Code

/plugin marketplace add krmj22/macos-mcp
/plugin install macos-mcp@krmj22-plugins

Запустите эти команды внутри Claude Code. Плагин подключает MCP-сервер через npx -y mcp-macos, поэтому отдельный шаг установки не требуется.

Установка из npm

npm install -g mcp-macos
# or use npx via your client's MCP config (no global install needed)

Или установка через MCPB (Claude Desktop)

Скачайте пакет .mcpb из последнего релиза GitHub и перетащите его на Claude Desktop. Пакет включает предварительно собранный универсальный Swift-бинарник (arm64 + x86_64), поэтому Xcode Command Line Tools не требуются.

Или сборка из исходников

git clone https://github.com/krmj22/macos-mcp.git
cd macos-mcp
pnpm install
pnpm build

Проверка установки

macos-mcp --check   # or: node dist/index.js --check

Проверяет версию macOS, Node.js, бинарник EventKit, полный доступ к диску и разрешения автоматизации JXA.

Или использование как навыка вместо сервера

Скопируйте навык в каталог навыков вашего агента. Никакого MCP-сервера и схем инструментов в контексте.

git clone https://github.com/krmj22/macos-mcp.git
cp -R macos-mcp/skills/macos ~/.claude/skills/macos

Навык вызывает EventKitCLI, osascript и sqlite3 напрямую, поэтому ему нужен Swift-бинарник в PATH:

cd "$(mktemp -d)" && npm i mcp-macos --no-save \
  && mkdir -p ~/.local/lib/mcp-macos/bin \
  && cp node_modules/mcp-macos/bin/EventKitCLI ~/.local/lib/mcp-macos/bin/EventKitCLI \
  && ln -sf ~/.local/lib/mcp-macos/bin/EventKitCLI ~/.local/bin/EventKitCLI

Разрешения применяются одинаково в обоих случаях. См. Разрешения.

Инструменты

Работает как запись с подчёркиванием (reminders_tasks), так и с точкой (reminders.tasks).

Заметки по дизайну

• SQLite для чтения, JXA для записи. Чтение Mail через JXA не масштабируется, достигая 60-секундных тайм-аутов на реальных почтовых ящиках, а чтение Messages через JXA полностью сломано на macOS Sonoma и новее. Этот проект читает chat.db и Envelope Index Mail напрямую, включая таблицу соединений labels Gmail для аккаунтов [Gmail]/All Mail. Запись по-прежнему идёт через JXA, потому что Apple Events — единственный API, который её запускает. См. ADR-001.

• Гибридный бэкенд для каждого приложения. Каждое приложение использует мост, который работает: Swift CLI через EventKit для Reminders и Calendar, JXA для Notes, Contacts, записи Mail и отправки Messages, SQLite для чтения Mail и Messages. Диаграмма архитектуры показывает разветвление.

• Обогащение контактов между инструментами. Общий слой сопоставляет сырые номера телефонов и адреса электронной почты с именами контактов в Messages, Mail и Calendar. Массовый кэш через SQLite-хранилище AddressBook, менее 50 мс для 1100 записей; точечные запросы через JXA whose(). См. ADR-002.

• Предварительная проверка. macos-mcp --check проверяет версию macOS, Node.js, бинарник EventKit, полный доступ к диску и разрешения JXA перед запуском, с глубокими ссылками на соответствующие панели System Settings при любых сбоях.

Настройка

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

• Node.js 20+

• macOS

• Xcode Command Line Tools (компиляция Swift)

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

JSON-конфигурация одинакова для всех клиентов. Отличается только расположение.

{
  "mcpServers": {
    "macos-mcp": {
      "command": "npx",
      "args": ["mcp-macos"]
    }
  }
}

Разрешения

macOS запрашивает доступ при первом использовании. Нажмите Разрешить при появлении запроса.

Messages и Mail читают базы данных SQLite напрямую, поэтому вашему терминальному приложению (Terminal, iTerm2 и т. д.) нужен полный доступ к диску.

Запустите macos-mcp --check для проверки. См. Устранение неполадок, если что-то не работает.

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

Быстрые команды

# Open specific settings panes
open "x-apple.systempreferences:com.apple.preference.security?Privacy_Reminders"
open "x-apple.systempreferences:com.apple.preference.security?Privacy_Calendars"
open "x-apple.systempreferences:com.apple.preference.security?Privacy_Automation"
open "x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles"

Полный доступ к диску (Messages и Mail)

Messages и Mail читают базы данных SQLite (~/Library/Messages/chat.db и ~/Library/Mail/V10/MailData/Envelope Index). Для этого требуется полный доступ к диску для вашего терминального приложения.

# Find your real node binary (version managers use shims)
node -e "console.log(process.execPath)"

# Reveal it in Finder for drag-and-drop into FDA settings
open -R "$(node -e "console.log(process.execPath)")"

# Open Full Disk Access settings
open "x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles"

Пользователи менеджеров версий (Volta, nvm, fnm): команда node — это шим. System Settings нужен реальный бинарник:

System Settings может не показывать бинарники в скрытых каталогах. Используйте open -R выше, чтобы показать его в Finder, а затем перетащите в список FDA.

Автоматизация JXA (Notes, Mail, Contacts)

При первом использовании macOS запрашивает разрешение на автоматизацию. Предоставьте его через System Settings > Конфиденциальность и безопасность > Автоматизация.

Проверьте разрешения:

osascript -l JavaScript -e 'Application("Contacts").people().length'
osascript -l JavaScript -e 'Application("Calendar").calendars().length'
osascript -l JavaScript -e 'Application("Reminders").defaultList().name()'
osascript -l JavaScript -e 'Application("Mail").inbox().messages().length'
osascript -l JavaScript -e 'Application("Notes").notes().length'

Каждая команда должна возвращать значение. Зависание означает, что диалог разрешений пытается (и не может) появиться.

Метки Gmail / Отсутствующие сообщения входящих

Gmail хранит все сообщения в [Gmail]/All Mail и использует метки для членства в папках. Сервер проверяет и прямой почтовый ящик, и таблицу соединений меток. Если сообщения входящих Gmail отсутствуют, убедитесь, что приложение Mail полностью синхронизировано.

Разработка

pnpm install          # Install dependencies
pnpm build            # Build TypeScript + Swift binary
pnpm test             # Run full test suite
pnpm lint             # Lint and format (Biome + TypeScript)
pnpm dev              # Run from source via tsx

Точка входа для продакшена (bin/run.cjs) требует pnpm build. Для локальной разработки используйте pnpm dev.

Архитектура

flowchart LR
    Client[MCP Client<br/>Claude Code, Cursor, Desktop] -->|stdio| Server[macos-mcp]

    Server --> Swift[Swift CLI]
    Server --> JXA[JXA]
    Server --> SQLite[SQLite Readers]

    Swift -->|EventKit| Reminders[Reminders]
    Swift -->|EventKit| Calendar[Calendar]

    JXA -->|Apple Events| Notes[Notes]
    JXA -->|Apple Events| Contacts[Contacts]
    JXA -->|writes only| Mail[Mail]
    JXA -->|send only| Messages[Messages]

    SQLite -->|Envelope Index| Mail
    SQLite -->|chat.db| Messages
    SQLite -->|AddressBook| Enrich[Contact<br/>Enrichment Cache]

Три моста к приложениям Apple:

• EventKit (Swift-бинарник). Reminders, Calendar. Скомпилированный Swift CLI, возвращает JSON.

• JXA. Notes, запись Mail, Contacts. Скрипты запускаются через osascript -l JavaScript.

• SQLite. Чтение Messages (~/Library/Messages/chat.db), чтение Mail (~/Library/Mail/V10/MailData/Envelope Index). Чтение сообщений через JXA сломано на Sonoma и новее. Чтение почты через JXA слишком медленное для реальных почтовых ящиков.

Mail и Messages используют гибридный путь: JXA для записи (единственный способ запустить отправку/черновик), SQLite для чтения (единственный способ, который масштабируется). См. DECISION.md для записей архитектурных решений.

Зависимости

Среда выполнения: @modelcontextprotocol/sdk, zod

Разработка: typescript, tsx, jest, @biomejs/biome

Благодарности

Слой MCP-сервера начался с FradSer/mcp-server-apple-events (MIT). Здесь были добавлены Swift CLI для EventKit, пути чтения SQLite, обогащение контактов, предварительная проверка и поверхность навыка.

Лицензия

MIT

Вклад

См. CONTRIBUTING.md.