lane-mac-mcp

A read-only iMessage MCP server + CLI for macOS. One auditable file, no send capability.

Claude (via MCP) or you (via the CLI) can list conversations, read a chat, and search message history — and nothing else. Read-only by construction: v1 contains no send code at all. All data access shells out to Apple's own /usr/bin/sqlite3 with -json -readonly against ~/Library/Messages/chat.db; contact names come from read-only queries against the local AddressBook databases.

Design constraints

The entire server is server.ts (~600 lines, comments included) so it can be audited end-to-end — the audited file is the running file, since Node ≥ 22.18 executes TypeScript directly with native type-stripping (no build step, no compiled artifacts). There are exactly two dependencies, pinned via package-lock.json: @modelcontextprotocol/sdk and zod. No network imports, no open ports — stdio JSON-RPC only, spawned as a child process by Claude Desktop; CLI runs are one-shot processes. There is no daemon: Claude Desktop starts and stops the server with the app (restart the app to reload code).

Related MCP server: imessage-rich-search

Requirements

macOS with Messages set up, Node.js ≥ 22.18, and Full Disk Access for whichever process runs the server: Terminal (or your terminal app) for CLI use, and Claude Desktop for MCP use. Grant it in System Settings → Privacy & Security → Full Disk Access, then restart the app. node server.ts doctor checks all of this and tells you what's missing.

Setup

git clone <this repo> && cd MacMCPServer
npm install          # installs the two pinned dependencies
node server.ts doctor

Then add the server to Claude Desktop's claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "lane-mac": {
      "command": "node",
      "args": ["/Users/you/Desktop/MacMCPServer/server.ts"]
    }
  }
}

Restart Claude Desktop. Three tools appear: list_chats, read_chat, search_messages.

CLI usage

node server.ts chats                                   # recent chats, names resolved
node server.ts chats --search "mom" --limit 5
node server.ts chats --awaiting-reply-only             # threads where the last word wasn't yours
node server.ts read "Martha" --limit 100               # fuzzy name; ambiguous → candidates
node server.ts read 42 --start-date 2024-01-01 --end-date 2024-06-30 --include-reactions
node server.ts search "dinner" --from "martha"         # last 30 days by default
node server.ts search "dinner" --start-date 2015-01-01 --deep   # older history + rich-text decode
node server.ts doctor

Output is JSON. search covers message.text with SQL LIKE; --deep additionally decodes messages whose text lives only in the attributedBody blob (bounded scan, slower). Tapback reactions are excluded everywhere unless --include-reactions.

Apple quirks handled

Timestamps are nanoseconds since 2001-01-01 (seconds on very old rows) — both are converted. Message text often lives in the attributedBody typedstream blob rather than message.text; it's decoded in JS with the known NSString heuristic. Contact names are matched by normalized last-10-digit phone or lowercased email across all AddressBook sources, degrading gracefully to raw numbers when contacts are unreadable.

Privacy & safety posture

The server can only ever read. It opens the databases with sqlite3's -readonly flag, contains no code path that writes to any database or sends any message, makes no network connections, and listens on no ports. User input is escaped into SQL string literals ('' doubling) and numerics are validated. doctor prints row counts only, never message content. Env overrides (CHAT_DB_PATH, SQLITE_BIN, ADDRESSBOOK_DIR) exist so tests never touch real data.

Testing

npm test

Black-box tests generate a synthetic chat.db and AddressBook fixture (including an attributedBody-only message, a tapback, and an unreplied incoming thread) and drive the real CLI and the real MCP stdio interface as child processes. Development never touches real data.

Roadmap (later, not v1)

Contact enrichment polish → Notes read via osascript → sends gated behind a SEND_ENABLED env var plus per-call approval.