{"id":51286551,"url":"https://github.com/cannavis/imessage-rich-search","last_synced_at":"2026-06-30T06:03:03.873Z","repository":{"id":354931765,"uuid":"1226068417","full_name":"cannavis/imessage-rich-search","owner":"cannavis","description":"Full-text search across macOS iMessages including link-preview metadata (titles, summaries, site names) that Messages.app indexes but chat.db's raw text column doesn't expose. CLI + MCP server for Claude Desktop. Zero runtime deps.","archived":false,"fork":false,"pushed_at":"2026-05-01T01:29:47.000Z","size":21,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-01T02:19:23.173Z","etag":null,"topics":["apple","chat-db","claude","claude-code","cli","full-text-search","imessage","link-preview","macos","mcp","mcp-server","messages","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cannavis.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-01T00:08:52.000Z","updated_at":"2026-05-01T01:37:56.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cannavis/imessage-rich-search","commit_stats":null,"previous_names":["cannavis/imessage-rich-search"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/cannavis/imessage-rich-search","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cannavis%2Fimessage-rich-search","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cannavis%2Fimessage-rich-search/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cannavis%2Fimessage-rich-search/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cannavis%2Fimessage-rich-search/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cannavis","download_url":"https://codeload.github.com/cannavis/imessage-rich-search/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cannavis%2Fimessage-rich-search/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34954283,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-30T02:00:05.919Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apple","chat-db","claude","claude-code","cli","full-text-search","imessage","link-preview","macos","mcp","mcp-server","messages","python"],"created_at":"2026-06-30T06:02:58.419Z","updated_at":"2026-06-30T06:03:03.858Z","avatar_url":"https://github.com/cannavis.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# imessage-rich-search\n\n\u003e Full-text search across macOS iMessages — **including the link preview metadata** (titles, summaries, site names) that Messages.app indexes but the raw `chat.db` text column never exposes.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)\n[![Platform: macOS](https://img.shields.io/badge/platform-macOS-lightgrey.svg)](#requirements)\n[![No deps](https://img.shields.io/badge/runtime%20deps-zero-brightgreen.svg)](#how-it-works)\n[![MCP](https://img.shields.io/badge/MCP-compatible-8A2BE2.svg)](#claude-desktop-mcp-server)\n\n## The problem this solves\n\nWhen you paste a URL into iMessage, macOS fetches a rich preview — title, summary, site name, hero image — and stores that metadata in `chat.db` as an NSKeyedArchiver blob in `message.payload_data`. **Messages.app's search bar reads it. The raw `chat.db` `text` column does not.**\n\nSo if a friend sent `https://x.com/foo/status/123` and the preview card said *\"Obsidian + Claude Code is the most underrated productivity stack\"* — searching for \"obsidian\" in any tool that only reads `text` returns **zero results**. Messages.app finds it. This tool finds it. They search the same surface.\n\n## What it is — and isn't\n\n**Is:** A read-only, local search over your `chat.db`. ~200 lines of stdlib Python. Zero runtime dependencies. CLI + optional MCP server for Claude Desktop.\n\n**Isn't:** A Messages replacement (no UI, no send/edit/delete). A way to access anyone else's messages. An iCloud sync tool — searches only what's locally on this Mac. An OCR / image / audio / sticker reader. A bypass for Full Disk Access — you must grant it explicitly.\n\n## Requirements\n\n| | |\n|---|---|\n| **OS** | macOS 11 Big Sur or newer (tested through macOS 26) |\n| **Architecture** | Apple Silicon (arm64) or Intel (x86_64) |\n| **Python** | Apple's system `/usr/bin/python3` (3.9, ships with Xcode Command Line Tools) — required, see [Why Apple's Python](#why-apples-python) |\n| **Permissions** | One specific Full Disk Access grant — see [Step 2](#install) |\n| **Disk** | ~30 KB code + ~15 MB venv |\n\nIf you don't have Command Line Tools, run `xcode-select --install` first.\n\n## Install\n\n### Step 1 — Run the installer (one command)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/cannavis/imessage-rich-search/main/install.sh | bash\n```\n\nWhat this does, in plain English:\n1. Verifies you're on macOS with Command Line Tools.\n2. Creates a virtual environment at `~/.local/share/imessage-rich-search` against Apple's system Python 3.9.\n3. Pulls and installs this package from GitHub into that venv.\n4. Symlinks three commands into `~/.local/bin`: `imessage-rich-search`, `imrs` (alias), `imessage-rich-search-mcp`.\n\nIf you'd rather not pipe `curl` into `bash`, do it manually:\n\n```bash\n/usr/bin/python3 -m venv ~/.local/share/imessage-rich-search\n~/.local/share/imessage-rich-search/bin/pip install --upgrade pip\n~/.local/share/imessage-rich-search/bin/pip install \"git+https://github.com/cannavis/imessage-rich-search@v0.2.1\"\nmkdir -p ~/.local/bin\nfor exe in imessage-rich-search imrs imessage-rich-search-mcp; do\n  ln -sf ~/.local/share/imessage-rich-search/bin/$exe ~/.local/bin/$exe\ndone\n```\n\nThe CLI works immediately after this:\n\n```bash\n~/.local/bin/imrs \"obsidian\" --limit 3\n```\n\nIf your shell can't find `imrs`, add `~/.local/bin` to your PATH:\n\n```bash\necho 'export PATH=\"$HOME/.local/bin:$PATH\"' \u003e\u003e ~/.zshrc \u0026\u0026 exec zsh\n```\n\n### Step 2 — Grant Full Disk Access to Apple's Python 3.9\n\n**You must add this exact path to FDA, or the MCP server (and any disclaimed call into chat.db) will fail with `authorization denied`.** This step does not affect the CLI when run from your own terminal.\n\n1. Open **System Settings → Privacy \u0026 Security → Full Disk Access**.\n2. Click the **+** button.\n3. In the file picker, press **⌘ + Shift + G** (Go to Folder).\n4. Paste this path **exactly**:\n\n   ```\n   /Library/Developer/CommandLineTools/Library/Frameworks/Python3.framework/Versions/3.9/bin\n   ```\n\n5. Hit Return — you'll see the contents of that `bin` folder.\n6. Select **`python3.9`** (not `python3`, which is a symlink).\n7. Click **Open**. It appears in the list as `python3.9`.\n8. Make sure the toggle is **ON**. Authenticate if prompted.\n\n### Step 3 — Wire the MCP server into Claude Desktop\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json` and merge this in (preserve any existing keys):\n\n```json\n{\n  \"mcpServers\": {\n    \"imessage-rich-search\": {\n      \"command\": \"/Users/YOUR_USERNAME/.local/bin/imessage-rich-search-mcp\"\n    }\n  }\n}\n```\n\nReplace `YOUR_USERNAME` with your actual username (`whoami` will tell you).\n\n### Step 4 — Restart Claude Desktop\n\n**⌘Q** (full quit — not just close-window) and relaunch. New chats will have a `search_imessages_rich` tool.\n\n## Verify it works\n\nCLI:\n```bash\nimrs \"obsidian\" --limit 3\n# 3 match(es) for 'obsidian':\n# [2026-04-08T22:56:23+00:00] -\u003e +1XXXXXXXXXX  (rowid=...)\n#   * preview: Claude Code + Obsidian Ultimate Guide (build an AI second brain)\n```\n\nMCP server (manual JSON-RPC handshake — same path Claude Desktop uses):\n```bash\n(printf '%s\\n%s\\n' \\\n  '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2025-06-18\",\"capabilities\":{},\"clientInfo\":{\"name\":\"test\",\"version\":\"0\"}}}' \\\n  '{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/call\",\"params\":{\"name\":\"search_imessages_rich\",\"arguments\":{\"query\":\"obsidian\",\"limit\":1}}}') \\\n| /Applications/Claude.app/Contents/Helpers/disclaimer ~/.local/bin/imessage-rich-search-mcp\n```\n\nYou should see two JSON-RPC responses. If the second one contains `\"isError\": true` and `\"authorization denied\"`, Step 2 (FDA grant) was missed or the toggle is off.\n\n## Usage\n\n```bash\nimrs \"obsidian\"                                  # search all conversations\nimrs \"obsidian\" --contact \"+14073993471\"         # restrict to one handle\nimrs \"claude code\" --json | jq '.[].preview[0]'  # JSON for piping\nimrs \"obsidian\" --limit 20 --db /backup/chat.db  # backup file\nimessage-rich-search --help                      # full options\n```\n\nOutput legend: `-\u003e` sent · `\u003c-` received · `*` preview hit · `rowid` cross-references back into `chat.db`.\n\n## Claude Desktop (MCP server)\n\nOnce Steps 1–4 above are done, Claude can call this tool directly:\n\n```\nsearch_imessages_rich(query, contact?, limit?)\n```\n\n- `query` — case-insensitive substring (required)\n- `contact` — optional handle filter, e.g. `\"+14073993471\"` or `\"name@example.com\"`\n- `limit` — max matches, default 50\n\nReturns newest-first matches with body, decoded preview metadata, handle, date, and rowid.\n\n## Why Apple's Python\n\nThis isn't arbitrary — it's the only thing that works inside Claude Desktop, and there's a clear reason:\n\nClaude Desktop spawns MCP servers through `/Applications/Claude.app/Contents/Helpers/disclaimer`, a tiny wrapper that calls `responsibility_spawnattrs_setdisclaim()`. This is an Apple API that **deliberately breaks the TCC responsibility chain** so the MCP server is treated as its own responsible process. The intent: prevent third-party MCP servers from silently inheriting Claude.app's broad permissions.\n\nConsequence: the spawned binary needs *its own* Full Disk Access grant — Claude.app's grant doesn't propagate. macOS resolves the venv's `python3` to its canonical Apple binary at `/Library/Developer/CommandLineTools/.../python3.9`, and that's the path TCC checks. Hence Step 2.\n\nIf you install with Homebrew Python or pyenv instead, the canonical path resolves somewhere else and TCC blocks the request. Apple's CLT Python is the path of least resistance.\n\nReferences:\n- [Qt: The Curious Case of the Responsible Process](https://www.qt.io/blog/the-curious-case-of-the-responsible-process)\n- [Michael Tsai's notes on `responsibility_spawnattrs_setdisclaim`](https://mjtsai.com/blog/2025/07/07/the-curious-case-of-the-responsible-process/)\n\n## How it works\n\n```\nchat.db (SQLite, opened with mode=ro)\n  └─ message\n       ├─ text                 ← raw text (what basic tools see)\n       ├─ payload_data  BLOB   ← NSKeyedArchiver bplist of LPLinkMetadata\n       │                         (title, summary, site, image refs)\n       └─ balloon_bundle_id    ← e.g. com.apple.messages.URLBalloonProvider\n\nFor every row matching the contact filter:\n  1. Read text + payload_data\n  2. plistlib.loads(payload_data) → walk $objects → collect strings\n  3. haystack = (text + '\\n'.join(preview_strings)).lower()\n  4. Match if query.lower() in haystack\n```\n\nWalking strings out of `$objects` avoids needing `ccl_bplist`, `pyobjc`, or full NSKeyedUnarchiver — for full-text search the leaf strings are all that matter.\n\n## Privacy \u0026 security\n\n- **Read-only.** Opens `chat.db` with SQLite URI flag `mode=ro`.\n- **Local-only.** No network calls. (`grep -r 'urllib\\|requests\\|http\\|socket' src/` returns nothing.)\n- **No telemetry.**\n- **Zero runtime dependencies** — nothing to be supply-chain-attacked through.\n- The FDA grant from Step 2 applies to Apple's system Python 3.9 system-wide. If you have `Terminal`, `bash`, or `Visual Studio Code` already in FDA, this isn't expanding your attack surface — those can already trivially shell out to `/usr/bin/python3`.\n\nSee [SECURITY.md](SECURITY.md) for vulnerability reporting.\n\n## Limitations\n\n- **Substring match only.** No FTS5, regex, or boolean operators. (Roadmap.)\n- **Local DB only.** If a message lives only in iCloud and isn't synced to this Mac's `chat.db`, this tool won't see it.\n- **Preview metadata depends on Messages.app having fetched it.** If a link card never loaded (offline send, expired URL), there's no `payload_data` to search.\n- **String extraction is lossy by design.** Image MIME types, dimension tuples like `{0, 0}`, and profile-image URLs may appear in raw output. They don't affect search hits.\n\n## Troubleshooting\n\n| Symptom | Fix |\n|---|---|\n| `imrs: command not found` | Add `~/.local/bin` to PATH: `echo 'export PATH=\"$HOME/.local/bin:$PATH\"' \u003e\u003e ~/.zshrc \u0026\u0026 exec zsh` |\n| `unable to open database file` from CLI in your terminal | Add your terminal app to FDA: System Settings → Privacy \u0026 Security → Full Disk Access. ⌘Q + relaunch the terminal. |\n| `authorization denied` from Claude Desktop's MCP call (CLI works fine) | Step 2 is missing or toggled off. Verify `python3.9` is in FDA list with toggle ON. ⌘Q + relaunch Claude Desktop. |\n| Claude Desktop doesn't see the tool at all | Validate JSON: `python3 -c \"import json; json.load(open('$HOME/Library/Application Support/Claude/claude_desktop_config.json'))\"`. Then ⌘Q + relaunch. |\n| Returns 0 matches but Messages.app finds them | Wrong `--contact` format. Drop `--contact` to confirm. Phone numbers must be E.164: `+14155551212`. |\n| Apple's Python 3.9 isn't at the expected path | `xcode-select -p` to verify CLT is installed. If installed but path differs (e.g., full Xcode), find it: `xcrun --find python3` |\n| Search slow on huge DBs | Linear scan + bplist parse per row. ~100k message DBs take a few seconds. FTS5 index is roadmap. |\n\n### Verify the TCC grant directly\n\nIf unsure whether Step 2 took effect, watch the system log while making a request:\n\n```bash\nlog stream --predicate 'process == \"tccd\"' --info | grep -E \"python3\\.9|chat\\.db|SystemPolicyAllFiles\"\n```\n\nYou want to see `Auth Right: Allowed (System Set)` for the `python3.9` binary. `Denied (Service Policy)` means the grant isn't in place.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). Issues and PRs welcome. Don't paste real chat content into public issues — redact phone numbers, names, and message text first.\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md).\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcannavis%2Fimessage-rich-search","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcannavis%2Fimessage-rich-search","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcannavis%2Fimessage-rich-search/lists"}