macsync/mcp/README.md

mac-sync MCP (@lilith/mac-sync-mcp)

A stdio MCP server that exposes mac-sync's own /my/* surface as tools. mac-sync owns the data (iMessage, contacts, prospects, calls, outbox in Postgres), so this talks to the mac-sync server directly — no quinn-api hop. It supersedes the mac-sync calls that previously lived in quinn-m-mcp.

Env

var	default	notes
MAC_SYNC_BASE_URL	http://209.38.51.98:3201	mac-sync server (DO backend droplet; override to wg http://10.9.0.5:3201)
MAC_SYNC_TOKEN	—	the server's shared service token (/my/* is serviceTokenAuth)

Tools

• Messages — search_messages (hybrid/lexical/semantic), list_conversations, get_thread
• Contacts — list_contacts, search_contacts_by_name
• Prospects (Handoff 01) — list_prospects, get_prospect
• Calls (Handoff 02) — recent_calls (since window; answers "did this lead also call?")
• Outbox (Handoff 03) — enqueue_reply (paced, channel-smart, scheduled; markReadOnSend option), outbox_status, outbox_stats
• Read-state (Handoff 04) — mark_conversation_read, mark_all_replied_read, conversation_read_state (logical-read; never touches Apple's chat.db)

Run

bun install
MAC_SYNC_TOKEN=... bun run src/index.ts   # stdio
bun run typecheck

Register with a client (.mcp.json)

{
  "mcpServers": {
    "mac-sync": {
      "type": "stdio",
      "command": "bun",
      "args": ["run", "<abs-path>/@mac-sync/mcp/src/index.ts"],
      "env": {
        "MAC_SYNC_BASE_URL": "http://209.38.51.98:3201",
        "MAC_SYNC_TOKEN": "<service-token>"
      }
    }
  }
}

Adjust <abs-path> to the host (the repo's .mcp.json uses /var/home/lilith/... on the deploy host). The token is a secret — do not commit it.