imsg — fast, local iMessage for your terminal & MCP

imsg — fast, local iMessage for your terminal & MCP

Package brand: imsg-mcp · CLI/MCP: imsg / imsg-mcp · PyPI today: pip install mac-imsg (target PyPI: imsg-mcp).

Read, search, and send iMessage from your terminal — or expose it to Claude,Cursor, VS Code, or any MCP client. Everything runs locally on your Mac:no cloud, no login, no account. Reads open ~/Library/Messages/chat.dbread-only; sends go through Messages.app.

macOS only. iMessage lives in Apple's local chat.db and Messages.app —there is no official API and no equivalent on Linux or Windows, so imsgonly runs on macOS. See Requirements for the Full DiskAccess setup every install needs.

Why another one? The hot path — decoding tens of thousands ofattributedBody typedstream blobs — is written in Rust (PyO3 + rusqlite),so reads and searches over a large history are several times faster than thepure-Python equivalent that other Messages servers use. Pure Python still shipsas a zero-dependency fallback, so it works even where the wheel doesn't.

Benchmark

Full-history search over a synthetic 50,000-message database (70% stored asattributedBody blobs), best-of-5, Apple Silicon (16 cores):

Two honest caveats, stated up front:

• Raw blob decoding is ~a wash — it's bound by allocating result strings, notCPU, so native code doesn't help. The win is in search, where Rustdecodes and filters across all cores and returns only the matches.
• It's 3.4×, not 16×, because the SQLite read and result marshalling are serialon both sides; only the decode+match parallelizes. The gap widens on largerhistories.

Reproduce: python bench/benchmark.py. Bonus: this search also findsmessages whose text lives in an attributedBody blob — which a plaintext LIKE query (used by Python-only Messages servers) silently misses.

Install

imsg is macOS-only. Pick one:

# Homebrew
brew install ml-lubich/tap/imsg

# pip
pip install mac-imsg

# uv (recommended) — provisions Python + the prebuilt wheel
uv tool install mac-imsg

# from a clone, building the Rust core yourself
git clone https://github.com/ml-lubich/imsg.git && cd imsg
uv tool install .

The PyPI package is mac-imsg — imsg-mcp (the eventual target name) wasalready registered when this shipped. The installed commands are alwaysimsg and imsg-mcp, regardless of package name.

Requirements

• macOS. Reads live at ~/Library/Messages/chat.db; sends go throughMessages.app AppleScript. Neither exists on Linux or Windows, so there's nocross-platform build.
• Full Disk Access for whichever app runs imsg:
  1. System Settings → Privacy & Security → Full Disk Access.
  2. Add the app that will run it — your terminal (Terminal/iTerm/Ghostty)for the CLI, or your MCP client (Claude Desktop, Cursor, VS Code, ClaudeCode) for the server.
  3. Fully quit and reopen that app — the permission doesn't take effectuntil relaunch.
• Messages.app signed in and able to send a normal message (only neededfor imsg send).

Run imsg doctor to check access and see which engine (Rust or Python) is live.

Specs live under docs/ (overview, architecture, design, API, testing).

CLI

imsg -h                           # commands (also: imsg <cmd> -h)
imsg doctor                       # check Full Disk Access + engine
imsg chats                        # recent conversations + their ids
imsg contacts                     # handles (numbers / emails) seen
imsg contacts -q 415              # filter handles by substring
imsg contacts -q Heupler          # or by AddressBook display name
imsg read -c +14155551234         # recent messages with a contact
imsg read --chat 42 --limit 100   # a specific conversation
imsg search "dinner"              # search message text
imsg attachments -c +14155551234  # list media/files with on-disk paths
imsg attachments -k audio         # only audio (image / video / application too)
imsg download -k image -o ./media # copy media out to a folder
imsg send +14155551234 "on my way"
imsg send "Joseph Heupler" "on my way"  # resolves to one contact, or errors
imsg version                      # installed package version
imsg agent schema                 # JSON schema of every stable command
imsg agent guide                  # markdown playbook for LLM agents

Every command accepts -h / --help with options, arguments, and examples(agent-friendly); imsg help <command> prints the same thing.

MCP server

The imsg-mcp entry point speaks MCP over stdio. Add it to any client:

Claude Code

claude mcp add --transport stdio --scope user imsg -- imsg-mcp

Claude Desktop / Cursor (mcpServers) · VS Code (servers):

{ "mcpServers": { "imsg": { "command": "imsg-mcp" } } }

Tools exposed: check_access, get_recent_messages, search_messages,list_chats, list_contacts, list_attachments, download_attachments,send_message (the only one with a side effect).

Contacts by name

-q on contacts and a name argument to send both resolve against thelocal AddressBook (~/Library/Application Support/AddressBook/Sources/*/AddressBook-v22.abcddb),read directly and read-only — never via osascript/Contacts.app. sendonly goes through when a name resolves to exactly one contact; an ambiguousor unmatched name raises an error listing the candidates and sends nothing.

Attachments

attachments / download cover images, audio, video, and documents. Messagesalready keeps these on disk under ~/Library/Messages/Attachments, sodownloading is a local copy — nothing is fetched over the network. --kind is amime-type prefix (image, audio, video, application). Existing files arenever overwritten (colliding names become -1, -2, …), and rows whose backingfile is missing — iCloud-only or pruned by Messages — are listed with exists: false and skipped on download rather than aborting the batch.

How it works

There is no official iMessage API. Every tool in this space does the same twolocal things; imsg just does the heavy half in Rust:

SQLite is the same C library everywhere, so the read speedup comes from doingthe per-message attributedBody decode and row marshalling natively instead ofin a Python loop. See bench/benchmark.py for themethodology — both engines run identical queries over an identical syntheticdatabase, and the pure-Python column is the same algorithm Python-only serversuse.

Privacy & security

• All database connections are opened read-only (mode=ro).
• Nothing is uploaded, mirrored, or indexed off-device.
• Sending is isolated in one function, escapes its AppleScript inputs, and isthe only operation that writes anything anywhere.
• Full Disk Access is broad — grant it only to apps you trust.

Development

git clone https://github.com/ml-lubich/imsg.git && cd imsg
uv venv && source .venv/bin/activate
uv pip install maturin
maturin develop            # builds the Rust core + installs the package
uv pip install -e ".[dev]"
pytest                     # tests run on the pure-Python path (and Rust if built)
python bench/benchmark.py  # regenerate the benchmark

License

MIT © ml-lubich. Not affiliated with Apple. Use responsibly and only withaccounts and conversations you own.