imessage-rich-search

Полнотекстовый поиск по iMessage в macOS — включая метаданные предварительного просмотра ссылок (заголовки, описания, названия сайтов), которые индексирует приложение «Сообщения», но которые никогда не отображаются в текстовом столбце chat.db.

👁 License: MIT
👁 Python 3.9+
👁 Platform: macOS
👁 No deps
👁 MCP

Какую проблему это решает

Когда вы вставляете URL в iMessage, macOS получает расширенный предварительный просмотр — заголовок, описание, название сайта, главное изображение — и сохраняет эти метаданные в chat.db в виде объекта NSKeyedArchiver в столбце message.payload_data. Панель поиска приложения «Сообщения» считывает их. Базовый текстовый столбец text в chat.db их не содержит.

Поэтому, если друг прислал вам https://x.com/foo/status/123, а в карточке предпросмотра было написано "Obsidian + Claude Code is the most underrated productivity stack" — поиск по слову "obsidian" в любом инструменте, который читает только столбец text, вернет ноль результатов. Приложение «Сообщения» находит это. Этот инструмент тоже находит. Они ищут в одной и той же области данных.

Related MCP server: iMessage MCP Server

Возможности

• Поиск по телу сообщения и декодированным метаданным предпросмотра ссылок за один проход

• Фильтрация по идентификатору (телефон / email)

• Вывод в читаемом человеком формате или JSON

• Только чтение chat.db (использует режим URI SQLite)

• Отсутствие зависимостей времени выполнения для CLI (только стандартная библиотека Python)

• Опциональный MCP-сервер, чтобы Claude Desktop / Claude.ai могли вызывать его напрямую

• Результаты от новых к старым, временные метки ISO 8601, стрелки направления, rowid для перекрестных ссылок

Что это такое — и чем не является

Является:

• Инструментом для поиска в режиме только чтения по вашей локальной базе chat.db

• Дополнением к MCP-инструментам для iMessage, которые видят только «сырой» текст

• ~200 строками кода на стандартном Python

Не является:

• Заменой приложения «Сообщения» (нет интерфейса, нельзя отправлять/редактировать/удалять)

• Способом получить доступ к чужим сообщениям

• Инструментом для синхронизации iCloud / между устройствами — поиск ведется только по тому, что локально на этом Mac

• Обходом ограничений «Полного доступа к диску» — вы должны предоставить его явно

• Средством распознавания OCR / изображений / аудио / стикеров / рукописного ввода (только текст + метаданные ссылок)

• Способом восстановить удаленные сообщения, если их нет в SQLite

Требования

Поля схемы chat.db, на которые он опирается (text, payload_data, balloon_bundle_id, handle.id), остаются стабильными со времен macOS 10.13 High Sierra; этот инструмент, вероятно, будет работать и на более старых версиях, хотя это не тестировалось.

Установка

Вариант А — pipx (рекомендуется, для MCP-сервера требуется системный Python)

pipx изолирует инструмент в собственном venv. Сначала установите pipx, если нужно:

brew install pipx
pipx ensurepath

Затем установите этот инструмент из GitHub. Используйте /usr/bin/python3 явно — это важно для MCP-сервера, так как macOS передает «Полный доступ к диску» от Claude.app только дочерним процессам, подписанным Apple. Python из Homebrew подписан сторонним разработчиком; системный /usr/bin/python3 подписан Apple и наследует права корректно. Если вам не нужен MCP-сервер (только CLI), подойдет любой Python 3.9+.

pipx install --python /usr/bin/python3 "git+https://github.com/cannavis/imessage-rich-search"

Это установит три команды в ваш PATH (в ~/.local/bin):

• imessage-rich-search — CLI

• imrs — короткий псевдоним для CLI

• imessage-rich-search-mcp — MCP-сервер

Вариант Б — pip в venv

git clone https://github.com/cannavis/imessage-rich-search
cd imessage-rich-search
/usr/bin/python3 -m venv .venv && source .venv/bin/activate
pip install -e .

Вариант В — один файл, без установки

CLI-модуль не имеет зависимостей. Вы можете скачать его через curl и запустить:

curl -O https://raw.githubusercontent.com/cannavis/imessage-rich-search/main/src/imessage_rich_search/cli.py
python3 cli.py "obsidian"

Предоставление полного доступа к диску (однократно, обязательно)

chat.db заблокирован средствами macOS TCC. Без полного доступа к диску вы получите ошибку unable to open database file.

1. Откройте Системные настройки → Конфиденциальность и безопасность → Полный доступ к диску

2. Нажмите + и добавьте приложение, из которого будете запускать скрипт:

   • Запускаете imessage-rich-search прямо в оболочке? → добавьте Терминал (или iTerm, Warp, Ghostty, Alacritty и т.д. — то, что вы используете)

   • Запускаете из Claude Desktop через MCP? → добавьте Claude.app

   • Запускаете из редактора скриптов или IDE? → добавьте это приложение

3. Полностью завершите и перезапустите это приложение (⌘Q, а не просто закрытие окна), чтобы разрешение вступило в силу

4. Проверка: python3 -c "import sqlite3; sqlite3.connect('file:'+__import__('os').path.expanduser('~/Library/Messages/chat.db')+'?mode=ro', uri=True).execute('SELECT COUNT(*) FROM message').fetchone()" — должно вывести число, а не ошибку

Использование

# Basic search across all conversations
imessage-rich-search "obsidian"

# Restrict to one contact
imessage-rich-search "obsidian" --contact "+14073993471"

# JSON for piping into jq, scripts, or another tool
imessage-rich-search "obsidian" --contact "+14073993471" --json | jq '.[].preview[0]'

# Limit results, point at a backup chat.db
imessage-rich-search "claude code" --limit 20 --db /path/to/chat.db

# Short alias
imrs "obsidian"

# Module form (no entry point needed)
python3 -m imessage_rich_search "obsidian"

Вывод

6 match(es) for 'obsidian':

[2026-04-08T22:56:23+00:00] -> +14073993471 (rowid=234953)
 url: https://x.com/aiedge_/status/2041908011078447222?s=42
 * preview: Claude Code + Obsidian Ultimate Guide (build an AI second brain)
...

-> = отправлено · <- = получено · * = строка предпросмотра, содержащая ваш запрос · rowid = ключ перекрестной ссылки в chat.db.

Использование в качестве MCP-сервера (Claude Desktop)

Позволяет Claude Desktop вызывать поиск напрямую во время диалогов.

1. Установите пакет, используя системный Python (Вариант А выше с --python /usr/bin/python3). Это обязательно: «Полный доступ к диску» в macOS передается от Claude.app только подписанным Apple подпроцессам. /usr/bin/python3 подписан Apple; Python из Homebrew / pyenv / asdf не подписан, и доступ будет молча отклонен tccd.

2. Найдите абсолютный путь к точке входа: which imessage-rich-search-mcp

3. Отредактируйте ~/Library/Application Support/Claude/claude_desktop_config.json:

   {
    "mcpServers": {
    "imessage-rich-search": {
    "command": "/full/path/from/which/imessage-rich-search-mcp"
    }
    }
   }

4. Убедитесь, что у Claude.app уже есть «Полный доступ к диску» (он есть по умолчанию, если вы предоставили его один раз — проверьте в Системных настройках → Конфиденциальность и безопасность → Полный доступ к диску)

5. Полностью завершите и перезапустите Claude Desktop (⌘Q)

Теперь Claude может вызывать search_imessages_rich(query, contact?, limit?) как инструмент.

Проверка работы наследования TCC

Если MCP-сервер возвращает "unable to open database file" внутри Claude Desktop, цепочка атрибуции запуска нарушена. Проверьте лог демона TCC в macOS:

log show --predicate 'process == "tccd"' --last 5m | grep -iE "imessage-rich|chat\.db|SystemPolicyAllFiles"

При корректной установке запрос будет разрешен (allowed). При некорректной вы увидите responsible_path=, указывающий на неподписанный Apple бинарный файл Python, за которым следует recording denied. Переустановите с помощью pipx install --python /usr/bin/python3 ... для исправления.

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

chat.db (SQLite, read-only)
 └─ message
 ├─ text ← raw text (what basic tools see)
 ├─ payload_data (BLOB) ← NSKeyedArchiver bplist of LPLinkMetadata
 │ (title, summary, site, image refs)
 └─ balloon_bundle_id ← e.g. com.apple.messages.URLBalloonProvider

For every row:
 1. Read text + payload_data
 2. plistlib.loads(payload_data) → walk $objects → collect strings
 3. Lower-case haystack = text + "\n".join(preview_strings)
 4. Match if query.lower() in haystack

Трюк с извлечением строк из объектов позволяет избежать необходимости в ccl_bplist, pyobjc или полной семантике NSKeyedUnarchiver — для полнотекстового поиска нас не интересует граф объектов, только конечные строки.

Конфиденциальность и безопасность

• Только чтение. Открывает chat.db с флагом SQLite URI mode=ro.

• Только локально. Никаких сетевых вызовов. Никогда. (grep -r 'urllib\|requests\|http' src/ ничего не возвращает.)

• Нет телеметрии.

• Данные не покидают ваш Mac, если вы сами не решите поделиться выводом.

• CLI не имеет зависимостей времени выполнения — нет ничего, что можно было бы атаковать через цепочку поставок.

• См. SECURITY.md для сообщения об уязвимостях.

Ограничения

• Только поиск по подстроке. Нет ранжирования FTS5, нет регулярных выражений, нет логических операторов. Добавьте их, если нужно (PR приветствуются).

• Только локальная БД. Если сообщение живет только в iCloud и не синхронизировано с chat.db на этом Mac, оно не появится.

• Метаданные предпросмотра зависят от того, загрузило ли их приложение «Сообщения». Если карточка ссылки не загрузилась (отправка офлайн, истекший URL), то payload_data для поиска нет.

• Извлечение строк является потерей данных по дизайну. Оно извлекает каждую строку из bplist; иногда вы можете увидеть MIME-типы изображений, кортежи размеров вроде {0, 0} или URL-адреса изображений профиля в списке предпросмотра. Они не влияют на результаты поиска, но появляются в «сыром» выводе.

• Полный доступ к диску — жесткое требование — обходных путей нет.

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

Участие в разработке

См. CONTRIBUTING.md. Проблемы и PR приветствуются.

Журнал изменений

См. CHANGELOG.md.

Лицензия

MIT — см. LICENSE.

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

• Схема chat.db от Apple, которая остается удивительно стабильной на протяжении десятилетия релизов macOS

• Людям, которые годами занимались реверс-инжинирингом payload_data / LPLinkMetadata

• Model Context Protocol за спецификацию MCP

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers

Tools

• search_imessages_richA