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)
¶
sync_status()
¶
Return sync progress from the most recent :meth:sync call.