Mac Messages MCP Server for iMessage Analysis

Overview

This MCP (Model Context Protocol) server bridges a local macOS Messages database to large language models (LLMs) so you can analyze iMessages and use LLMs as safe, auditable tooling around messages. Instead of uploading raw message data to an external service, the server exposes narrow, authenticated tooling endpoints that LLMs can call via the MCP pattern (tooling requests/responses). Typical capabilities include validating phone numbers, extracting attachments and contacts, summarizing group chats, and sending or receiving messages under explicit developer control.

Running the server locally keeps message data on-device while letting models operate on structured, context-aware pieces of the Messages DB. It’s useful for building assistants that need message context (e.g., inbox summarization, contact enrichment, or automated replies) without giving LLMs unbounded access to your entire database.

Features

• Securely read the local Messages DB (chat.db) and expose controlled query tools
• Phone number validation and normalization against local contact data
• Attachment extraction and thumbnail/metadata access for images, videos, and files
• Contact lookup and enrichment (name, handles, associated numbers)
• Group chat analysis (participant lists, threading, activity summaries)
• Send and receive tooling with explicit enable/disable switch
• MCP-compatible endpoints so LLMs can call tools and receive structured results
• Local-first design: keep data on the Mac; enforce authentication and TLS for network access

Installation / Configuration

1. Clone the repository:

git clone https://github.com/carterlasalle/mac_messages_mcp.git
cd mac_messages_mcp

2. Install dependencies

Check the repository to determine the runtime. If package.json exists:

# Node.js
npm install
# or
yarn install

If requirements.txt exists:

# Python
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

3. Create a configuration file (.env or config.yml). Example environment variables:

# .env example
MESSAGES_DB_PATH=~/Library/Messages/chat.db
MCP_PORT=8080
MCP_API_KEY=replace-with-secure-token
LLM_ENDPOINT=https://localhost:1234/llm
ALLOW_SEND=false
TLS_CERT_PATH=/path/to/cert.pem
TLS_KEY_PATH=/path/to/key.pem

4. Run the server

# Node example
npm start

# Python example
python -m mac_messages_mcp.server --config .env

Notes:

• The default Messages DB path on macOS is ~/Library/Messages/chat.db. The server needs read access; for send/receive tooling it may need AppleScript permissions or ChatKit entitlement equivalents — follow macOS security prompts.
• For network exposure, bind to localhost by default and use TLS and an API key for added protection.

Available Tools / Resources

The server exposes a set of MCP-style tools (HTTP endpoints that return structured JSON). Typical tools include:

• phone_validation

  • Purpose: Normalize and validate a phone number against contacts and message history.
  • Request: POST /mcp/tools/phone_validation { “phone”: “+1-555-123-4567” }
  • Response: { “valid”: true, “normalized”: “+15551234567”, “contact_id”: 42 }

• contacts

  • Purpose: Lookup contacts by name, handle, or phone number.
  • Request: GET /mcp/tools/contacts?q=Alice
  • Response: list of contact objects (name, handles, phones, last_message_id)

• attachments

  • Purpose: List or fetch message attachments (images, videos, files).
  • Request: GET /mcp/tools/attachments?conversation_id=100&limit=10
  • Response: attachment metadata and optionally a signed local URL for download

• group_chat_summary

  • Purpose: Generate a summary of a group conversation, participants, and recent topics.
  • Request: POST /mcp/tools/group_chat_summary { “conversation_id”: 100, “since_days”: 7 }
  • Response: structured summary with highlights and activity metrics

• send_message (opt-in)

  • Purpose: Send a message via the Messages app (requires explicit opt-in).
  • Request: POST /mcp/tools/send_message { “to”: “+15551234567”, “text”: “Hello” }
  • Response: success/failure with message_id

Authentication:

• Every request must