imessage-rich-search

macOS iMessage 전체 텍스트 검색 — Messages.app은 인덱싱하지만 원본 chat.db 텍스트 열에서는 노출되지 않는 링크 미리보기 메타데이터(제목, 요약, 사이트 이름)를 포함합니다.

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

해결하는 문제

iMessage에 URL을 붙여넣으면 macOS는 풍부한 미리보기(제목, 요약, 사이트 이름, 대표 이미지)를 가져와 message.payload_data의 NSKeyedArchiver 블롭으로 chat.db에 저장합니다. Messages.app의 검색창은 이를 읽지만, 기본적인 chat.db text 열에는 이 정보가 포함되어 있지 않습니다.

따라서 친구가 https://x.com/foo/status/123을 보냈고 미리보기 카드에 *"Obsidian + Claude Code is the most underrated productivity stack"*이라고 적혀 있다면, text만 읽는 도구에서 "obsidian"을 검색하면 결과가 0개로 나옵니다. Messages.app은 이를 찾지만, 이 도구도 이를 찾습니다. 두 도구 모두 동일한 영역을 검색합니다.

Related MCP server: iMessage MCP Server

기능

• 메시지 본문 및 디코딩된 링크 미리보기 메타데이터를 한 번에 검색

• 핸들(전화번호/이메일)별 필터링

• 사람이 읽을 수 있는 형식 또는 JSON 출력

• chat.db 읽기 전용 (SQLite URI 모드 사용)

• CLI에 대한 런타임 종속성 없음 (Python 표준 라이브러리만 사용)

• Claude Desktop / Claude.ai가 직접 호출할 수 있는 선택적 MCP 서버

• 최신순 결과, ISO 8601 타임스탬프, 방향 화살표, 상호 참조를 위한 rowid 제공

무엇이며, 무엇이 아닌가

무엇인가:

• 로컬 chat.db에 대한 읽기 전용 포렌식/아카이브 검색 도구

• 원시 텍스트만 볼 수 있는 기존 MCP iMessage 도구의 보완 도구

• 약 200줄의 표준 라이브러리 Python 코드

무엇이 아닌가:

• Messages.app 대체품 (UI 없음, 전송/편집/삭제 기능 없음)

• 다른 사람의 메시지에 접근하는 방법

• iCloud / 기기 간 동기화 도구 — 이 Mac에 로컬로 저장된 메시지만 검색

• 전체 디스크 접근 권한 우회 도구 — 명시적으로 권한을 부여해야 함

• OCR / 이미지 / 오디오 / 스티커 / 필기 인식기 (텍스트 + 링크 메타데이터만 지원)

• SQLite에 남아 있는 것 이상의 삭제된 메시지 복구 도구

요구 사항

이 도구가 의존하는 chat.db 스키마 필드(text, payload_data, balloon_bundle_id, handle.id)는 macOS 10.13 High Sierra 이후로 안정적이었으며, 공식적으로 명시된 버전보다 이전 버전에서도 작동할 가능성이 높습니다(테스트되지 않음).

설치

옵션 A — pipx (권장, MCP 서버를 위해 시스템 Python 필요)

pipx는 도구를 자체 가상 환경에 격리합니다. 필요한 경우 먼저 pipx를 설치하세요:

brew install pipx
pipx ensurepath

그런 다음 GitHub에서 이 도구를 설치하세요. /usr/bin/python3를 명시적으로 사용하세요 — macOS는 Claude.app에서 Apple 서명된 자식 프로세스로만 전체 디스크 접근 권한을 전파하기 때문에 MCP 서버에 중요합니다. Homebrew Python은 타사 서명이 되어 있지만, 시스템 /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 서버

옵션 B — venv에 pip 설치

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 .

옵션 C — 단일 파일, 설치 없음

CLI 모듈은 종속성이 없습니다. curl로 다운로드하여 실행할 수 있습니다:

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

전체 디스크 접근 권한 부여 (1회 필수)

chat.db는 macOS TCC에 의해 잠겨 있습니다. 전체 디스크 접근 권한이 없으면 unable to open database file 오류가 발생합니다.

1. 시스템 설정 → 개인정보 보호 및 보안 → 전체 디스크 접근 권한을 엽니다.

2. **+**를 클릭하고 이 도구를 실행할 앱을 추가합니다:

   • 셸에서 직접 imessage-rich-search를 실행하는 경우? → 터미널(또는 iTerm, Warp, Ghostty, Alacritty 등 실제로 사용하는 터미널)을 추가합니다.

   • MCP를 통해 Claude Desktop에서 실행하는 경우? → 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을 사용하여 패키지를 설치합니다(위의 옵션 A에서 --python /usr/bin/python3 사용). 이는 필수입니다. macOS 전체 디스크 접근 권한은 Claude.app에서 Apple 서명된 하위 프로세스로만 전파되기 때문입니다. /usr/bin/python3는 Apple 서명이 되어 있지만, Homebrew / pyenv / asdf로 설치된 Python은 그렇지 않으며 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 상속 작동 확인

Claude Desktop 내에서 MCP 서버가 "unable to open database file"을 반환한다면, 생성 속성 체인이 끊어진 것입니다. macOS의 TCC 데몬 로그를 확인하세요:

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

정상적인 설치는 요청이 **허용(allowed)**되는 것으로 표시됩니다. 잘못된 설치는 Apple 서명이 없는 Python 바이너리를 가리키는 responsible_path=와 그 뒤에 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

"$objects에서 문자열 추출" 트릭은 ccl_bplist, pyobjc 또는 전체 NSKeyedUnarchiver 의미론이 필요하지 않습니다. 전체 텍스트 검색의 경우 객체 그래프가 아닌 리프 문자열만 중요하기 때문입니다.

개인정보 보호 및 보안

• 읽기 전용. SQLite URI 플래그 mode=ro로 chat.db를 엽니다.

• 로컬 전용. 네트워크 호출이 전혀 없습니다. (grep -r 'urllib\|requests\|http' src/ 결과 없음.)

• 텔레메트리 없음.

• 데이터 유출 없음. 출력을 공유하기로 선택하지 않는 한 데이터는 Mac을 떠나지 않습니다.

• CLI는 런타임 종속성이 없으므로 공급망 공격을 받을 요소가 없습니다.

• 취약점 보고는 SECURITY.md를 참조하세요.

제한 사항

• 부분 일치 검색만 지원. FTS5 순위 지정, 정규식, 불리언 연산자 없음. 원하시면 추가하세요(PR 환영).

• 로컬 DB만 지원. 메시지가 iCloud에만 있고 이 Mac의 chat.db에 동기화되지 않은 경우 나타나지 않습니다.

• 미리보기 메타데이터는 Messages.app이 가져온 경우에만 작동. 링크 카드가 로드되지 않은 경우(오프라인 전송, 만료된 URL) 검색할 payload_data가 없습니다.

• 문자열 추출은 설계상 손실이 발생함. bplist에서 모든 문자열을 가져오므로 미리보기 목록에 이미지 MIME 유형, {0, 0}과 같은 차원 튜플 또는 프로필 이미지 URL이 가끔 보일 수 있습니다. 검색 결과에는 영향을 주지 않지만 원시 출력에는 나타납니다.

• 전체 디스크 접근 권한은 필수 요구 사항입니다. 우회 방법이 없습니다.

문제 해결

기여

CONTRIBUTING.md를 참조하세요. 이슈와 PR은 언제나 환영합니다.

변경 로그

CHANGELOG.md를 참조하세요.

라이선스

MIT — LICENSE를 참조하세요.

감사의 말

• 10년 넘게 macOS 릴리스 전반에 걸쳐 놀라울 정도로 안정적인 Apple의 chat.db 스키마

• 수년간 payload_data / LPLinkMetadata를 리버스 엔지니어링한 분들

• MCP 사양을 제공한 Model Context Protocol

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers

Tools

• search_imessages_richA