Skip to content

imessage

diapason.connectors.imessage

iMessage connector — reads directly from the macOS Messages SQLite database.

No API calls, no OAuth. The connector opens ~/Library/Messages/chat.db in read-only mode and yields one :class:Document per message that has non-NULL text.

Requires Full Disk Access granted to the terminal / app in System Settings → Privacy & Security → Full Disk Access.

Timestamp notes

The iMessage database stores timestamps as nanoseconds since the Apple epoch of 2001-01-01 00:00:00 UTC. Conversion formula::

dt = datetime(2001, 1, 1, tzinfo=utc) + timedelta(seconds=apple_ns / 1_000_000_000)

IMessageConnector

Bases: BaseConnector

Connector that reads messages from the macOS Messages SQLite database.

Parameters

db_path: Path to chat.db. Defaults to ~/Library/Messages/chat.db.

disconnect()

Mark the connector as disconnected.

is_connected()

Whether Messages' database can actually be READ, not merely seen.

This answered exists(), which is True under macOS TCC even while every read is refused — so the connector announced itself connected to a database it could not open, the sync returned nothing, and nothing said why. Fix on the user's side: grant Full Disk Access.

mcp_tools()

Expose two MCP tool specs for real-time iMessage queries.

sync(*, since=None, cursor=None)

Read messages from chat.db and yield one :class:Document each.

Parameters

since: If provided, skip messages whose timestamp is before this datetime. cursor: Not used for this local connector (included for API compatibility).

Yields

Document One document per message with non-NULL text.

sync_status()

Return sync progress from the most recent :meth:sync call.