Skip to content

apple_contacts

diapason.connectors.apple_contacts

Apple Contacts connector — reads directly from the macOS Contacts SQLite database.

No API calls, no OAuth. The connector opens ~/Library/Application Support/AddressBook/AddressBook-v22.abcddb in read-only mode and yields one :class:Document per contact.

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

Timestamp notes

The Contacts database stores timestamps as seconds since the Apple epoch of 2001-01-01 00:00:00 UTC.

AppleContactsConnector

Bases: BaseConnector

Connector that reads contacts from the macOS Contacts SQLite database.

Parameters

db_path: Path to AddressBook-v22.abcddb. Defaults to ~/Library/Application Support/AddressBook/AddressBook-v22.abcddb.

disconnect()

Mark the connector as disconnected.

is_connected()

Return True if any AddressBook database exists.

mcp_tools()

Expose MCP tool specs for real-time Apple Contacts queries.

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

Read contacts from AddressBook and yield one :class:Document each.

Parameters

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

Yields

Document One document per contact with all fields as structured text.

sync_status()

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