Мультимодальный MCP-сервер для iMessage

Самый полный MCP-сервер для iMessage для Claude. Чтение полных бесед, поиск сообщений, просмотр вложений с изображениями, отправка сообщений, поиск контактов и реакции на сообщения — всё из Claude Desktop или Claude Code.

Зачем это нужно

Все остальные MCP-инструменты для iMessage запрашивают столбец text в chat.db от Apple. Проблема в том, что в современных macOS (14+) 93% сообщений хранятся в attributedBody, а не в text. Эти инструменты молча возвращают пустые или неполные беседы.

Этот сервер восстанавливает бинарный формат NSAttributedString от Apple, чтобы извлечь фактическое содержимое сообщения, предоставляя вам доступ к полной истории сообщений.

Related MCP server: jons-mcp-imessage

Возможности

Мультимодальность: Claude может видеть ваши фотографии

При использовании get_attachment изображения возвращаются в виде блоков содержимого base64, которые Claude может фактически просматривать. Фотографии HEIC (стандарт iPhone) автоматически конвертируются в JPEG. Это означает, что Claude может:

• Описывать, что находится на фотографии, которую вам кто-то прислал

• Читать текст/скриншоты из изображений

• Анализировать визуальный контент в ваших беседах

Требования

• macOS (этот сервер читает локальную базу данных iMessage)

• Node.js >= 18 и < 26. Рекомендуется Node 24 LTS, так как заблокированная собственная зависимость SQLite несовместима с Node 26.

• Полный доступ к диску для вашего терминального приложения (Системные настройки > Конфиденциальность и безопасность > Полный доступ к диску). Это охватывает как базу данных iMessage, так и базу данных AddressBook, используемую для разрешения имён контактов — приложение Контакты запускать не нужно.

Установка

git clone https://github.com/tszaks/imessage-mcp.git
cd imessage-mcp
npm install

Настройка

Claude Desktop

Добавьте в ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "imessage": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/path/to/imessage-mcp/index.js"]
    }
  }
}

Важно: Используйте полный путь к вашему бинарному файлу Node.js (например, /opt/homebrew/bin/node), а не просто node. Приложения macOS для рабочего стола не наследуют PATH вашей командной оболочки, и использование простой команды node часто приводит к разрешению старой системной Node, что вызывает сбои собственных модулей.

Claude Code

Добавьте в ваш .mcp.json:

{
  "mcpServers": {
    "imessage": {
      "command": "node",
      "args": ["/path/to/imessage-mcp/index.js"]
    }
  }
}

В Claude Code node обычно разрешается корректно, так как наследует окружение вашей командной оболочки.

Примеры использования

"Покажи мои последние сообщения" — читает ваши последние беседы

"Что мама написала мне сегодня?" — разрешает "Мама" в номер телефона через вашу адресную книгу, загружает беседу

"Найди в моих сообщениях 'подтверждение рейса'" — полнотекстовый поиск по всем сообщениям

"Найди перспективы для обращений за последние 7 дней, которые ответили и требуют повторного контакта" — возвращает структурированных кандидатов для обращений с метками риска

"Предпросмотри эту партию из 10 повторных текстов" — возвращает точных получателей, сообщения, предупреждения и токен утверждения перед отправкой

"Покажи недавние ошибки доставки" — сообщает об исходящих сообщениях, которые Messages пометил как неудачные или ожидающие, включая информацию о том, восстановила ли более поздняя отправка SMS/RCS ветку

"Покажи фотографию из сообщения 538516" — возвращает фактическое изображение для просмотра и описания Claude

"Отправь 'Опоздаю на 10 минут' на +1234567890" — отправляет iMessage (требуется подтверждение)

Флаги релиза

Флаги релиза включаются опционально через окружение MCP-сервера:

{
  "mcpServers": {
    "imessage": {
      "command": "node",
      "args": ["/path/to/imessage-mcp/index.js"],
      "env": {
        "IMESSAGE_MCP_RELEASES": "auto_sms_fallback,cleanup_failed_imessage_after_sms_fallback,message_mutation_tools,experimental_message_ui_actions,read_receipts"
      }
    }
  }
}

Инструменты для мутации

delete_messages принимает точные идентификаторы строк сообщений (ROWID):

{ "message_ids": ["538516", "538517"] }

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

delete_threads — это двухэтапный процесс с точной партией:

{ "chat_ids": [101, 102] }

Предпросмотр возвращает один approval_token для этого упорядоченного списка и метаданные ветки, показанные в предпросмотре. Для удаления отправьте тот же упорядоченный chat_ids, confirm: true и этот токен:

{ "chat_ids": [101, 102], "confirm": true, "approval_token": "..." }

Изменение порядка, списка или токена приводит к отказу запроса.

edit_message и undo_send_message являются экспериментальными, поскольку Messages не предоставляет первоклассных команд AppleScript для этих действий. Они открывают беседу, находят видимый исходящий пузырь по фрагменту текста, используют контекстное меню, а затем проверяют результат. Они предназначены для влияния на фактическое поведение Messages, а не для поддельных локальных изменений БД.

Необязательная настройка:

IMESSAGE_MCP_SEND_VERIFY_DELAY_MS=2500

Это контролирует, как долго MCP ожидает перед проверкой локальной базы данных Messages на наличие новой исходящей строки.

Как это работает

Исправление attributedBody

База данных iMessage от Apple (~/Library/Messages/chat.db) имеет два столбца для содержимого сообщения:

• text — устаревший столбец с обычным текстом (используется в старых версиях macOS)

• attributedBody — сериализованный блоб NSAttributedString (используется в macOS 14+)

В современных macOS Apple постепенно переносила хранение сообщений в attributedBody для поддержки форматированного текста, упоминаний и форматирования. Столбец text всё чаще является просто устаревшим запасным вариантом, который часто равен NULL.

Этот сервер обнаруживает сообщения с NULL в text и извлекает содержимое из attributedBody, анализируя бинарный формат NSTypedStream:

1. Находит маркер NSString в бинарном блобе

2. Пропускает заголовочные байты типа (01 94 84 01 2b)

3. Декодирует префикс длины (один байт для коротких сообщений, несколько байтов для длинных)

4. Извлекает текстовую нагрузку UTF-8

Обработка вложений

Вложения iMessage хранятся в ~/Library/Messages/Attachments/ с путями, отслеживаемыми в таблице attachment. Инструмент get_attachment:

1. Запрашивает метаданные вложения для данного ID сообщения

2. Преобразует путь ~/Library/Messages/... в абсолютный путь

3. Для JPEG/PNG/GIF/WebP: читает файл и возвращает содержимое изображения в base64

4. Для HEIC (стандарт iPhone): конвертирует в JPEG с помощью macOS sips перед возвратом

5. Для других файлов: возвращает метаданные и путь к файлу

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

"Не удалось открыть базу данных iMessage"

Предоставьте полный доступ к диску вашему терминальному приложению: Системные настройки > Конфиденциальность и безопасность > Полный доступ к диску.

Поиск контакта не возвращает результатов

Разрешение контактов читает базы данных SQLite адресной книги macOS напрямую (приложение Контакты не требуется). Убедитесь, что предоставлен полный доступ к диску. Если контакт был только что добавлен, перезапустите MCP-сервер, чтобы обновить кэш.

Сбой собственного модуля / "NODE_MODULE_VERSION mismatch"

Пересоберите собственные зависимости: npm rebuild. Это происходит, когда меняется версия Node.js. Также убедитесь, что конфигурация Claude Desktop использует полный путь к node (см. раздел Настройка выше).

Отсутствуют сообщения из беседы

Это именно та ошибка, которую исправляет этот сервер. Убедитесь, что вы используете последнюю версию, включающую извлечение attributedBody.

Лицензия

MIT

Краткое руководство TL;DR

npm install
node index.js

Затем добавьте сервер в конфигурацию вашего MCP-клиента и предоставьте приложению терминала Full Disk Access.

Как это работает (TL;DR)

• Читает базу данных SQLite iMessage в macOS

• Декодирует современные полезные нагрузки attributedBody для полного текста сообщений

• Предоставляет инструменты для работы с беседами/поиском/вложениями через MCP

• Использует AppleScript для отправки сообщений и реакций с явными подтверждениями

Быстрое копирование для LLM

Используйте кнопку копирования в этом блоке кода в GitHub.

Repo: imessage-mcp
Goal: Full iMessage MCP including attachments and send/reaction actions.
Setup:
1) npm install
2) Grant Full Disk Access to terminal app
3) Add MCP config entry for index.js
Use:
- read_recent_messages, search_messages, get_conversation
- list_chats_structured, get_conversation_by_chat_id, find_outreach_followups
- get_attachment for image/file analysis
- send_message/send_message_batch/react_to_message with explicit confirm flag
How it works:
- SQLite + attributedBody decoding + AppleScript actions wrapped as MCP tools