Mac Messages Host

Your Mac's entire Apple Messages (iMessage/SMS) history, read-only, for AI agents — one batched tool over REST/OpenAPI and streamable HTTP MCP.

• One tool, batched requests: a single messages(requests: str) tool takes a JSON array of requests and returns an aligned JSON array of responses — one call does many independent ops. Served identically over REST (POST /api/messages) and MCP (/mcp/).
• Read-only by construction: the database is opened with SQLite mode=ro; there is no write path. Nothing can be sent, edited, or deleted.
• Modern macOS body decoding: message text stored in attributedBody typedstream blobs (Ventura+) and edit history in message_summary_info plists is decoded transparently.
• Auto-generated tool prompt: the AI-facing prompt is generated from the Pydantic models (~615 gpt-4o tokens, counted by tiktoken and enforced by a test); a tool_prompt.md snapshot is kept in sync by a drift test.

Install

Requires Python 3.11+ on macOS.

pip install .            # or: pip install -e . for development
mmhost info              # permission check + database status
mmhost start             # serve API + MCP on http://127.0.0.1:8761

macOS permissions (important)

~/Library/Messages/chat.db is protected by macOS TCC. The process that runs mmhost needs Full Disk Access:

System Settings → Privacy & Security → Full Disk Access → enable your terminal app (or whatever launches the server), then restart it.

mmhost info tells you immediately whether the database is readable.

Endpoints

Endpoint	Purpose
POST /api/messages	The batched tool (REST)
/api/openapi.json	OpenAPI schema
/api/docs	Interactive docs
/api/health	Liveness probe
/mcp/	Streamable-HTTP MCP endpoint (single messages tool)

Auth

Authorization: Bearer <token> when admin_token is configured (persisted config, MMHOST_ADMIN_TOKEN, or --admin-token). With no token configured, access is open — safe because the server binds 127.0.0.1 by default.

Request kinds

• get_info — database status, counts, history date range
• list_chats — conversations by recent activity (filter, paginate)
• get_chat — a chat's transcript (paginate older via before)
• get_recent — newest messages across all chats (poll via since)
• search_messages — case-insensitive substring search over bodies

See tool_prompt.md for the exact AI-facing documentation (generated from the models).

Example

curl -s http://127.0.0.1:8761/api/messages \
  -H 'Content-Type: application/json' \
  -d '{"requests": "[{\"kind\":\"list_chats\",\"limit\":3}]"}'

MCP client configuration

{
  "mcpServers": {
    "mac-messages": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:8761/mcp/"
    }
  }
}

Configuration

Persisted at the platform config dir (~/Library/Application Support/mac_messages_host/config.json on macOS); override the location with MMHOST_CONFIG. Server-level settings only — see example.env.

Development

pip install -e '.[dev]'
pytest
# after changing request models:
python -m tests.regenerate_tool_prompt

Architecture follows the oWoHo AI Tool Server pattern (pure core library + derived FastAPI/FastMCP/CLI interfaces), like reddit_tool_server and obsidian_ai_miniserver.

License

MIT — see LICENSE.md.