Mac Messages MCP

What is Mac Messages MCP about?

Securely bridges the macOS Messages app to LLMs through MCP, allowing programs to read recent conversations, search by contact or content, and send messages that automatically choose iMessage or SMS based on recipient availability.

How to use Mac Messages MCP?

1. Prerequisites: macOS 11+, Python 3.10+, and the uv package manager (install via brew install uv).
2. Grant Full Disk Access to your terminal or IDE so the script can read the Messages database.
3. Install the package:

   uv pip install mac-messages-mcp   # from PyPI
   # or from source
   git clone https://github.com/carterlasalle/mac_messages_mcp.git
   cd mac_messages_mcp
   uv install -e .
   

4. Run the MCP server (single instance only):

   mac-messages-mcp          # starts the server
   # or equivalently
   uvx mac-messages-mcp
   

5. Integrate with Claude Desktop or Cursor by adding the command uvx mac-messages-mcp to the MCP server list, as shown in the README.

Key Features of Mac Messages MCP

• Universal message sending with automatic iMessage ↔ SMS/RCS fallback
• Smart detection of iMessage availability per recipient
• Retrieval of recent messages (customizable time window)
• Contact and phone‑number filtering
• Fuzzy content search across conversations
• Full support for group chats and attachment processing
• Robust phone‑number validation
• Cross‑platform operation for iPhone, iPad, Mac, and Android users

Use Cases of Mac Messages MCP

• Personal automation: Let an LLM draft and send replies based on conversation context.
• Chat analytics: Perform sentiment or keyword analysis on a user’s iMessage history.
• Customer support: Route messages to the appropriate channel (iMessage for Apple users, SMS for Android users) automatically.
• Archiving & compliance: Export filtered conversation logs for backup or legal review.
• Research: Study communication patterns without manual copying.

FAQ from the Mac Messages MCP

Q: Which macOS version is required? A: macOS 11 (Big Sur) or newer.

Q: Do I need a paid Apple ID or iMessage account? A: No, the tool works with the local Messages database of any logged‑in Apple ID.

Q: Can the server send SMS to Android contacts? A: Yes, it falls back to SMS/RCS when the recipient does not have iMessage.

Q: Why is Full Disk Access necessary? A: Access to the Messages SQLite database is restricted; Full Disk Access grants read/write rights.

Q: How do I install uv if I’m not on macOS? A: Follow the instructions on the uv GitHub page; on Linux you can use curl -LsSf https://astral.sh/uv/install.sh | sh.

Q: Can I run the server in both Claude Desktop and Cursor simultaneously? A: No, only one instance should run at a time to avoid database lock conflicts.

Q: Is my conversation data safe? A: The server runs locally and never sends data to external services unless you explicitly forward it.

Mac Messages MCP

A Python bridge for interacting with the macOS Messages app using MCP (Multiple Context Protocol).

Quick Install

For Cursor Users

Click the button above to automatically add Mac Messages MCP to Cursor

For Claude Desktop Users

See the Integration section below for setup instructions.

Features

• Universal Message Sending: Automatically sends via iMessage or SMS/RCS based on recipient availability
• Smart Fallback: Seamless fallback to SMS when iMessage is unavailable (perfect for Android users)
• Message Reading: Read recent messages from the macOS Messages app
• Contact Filtering: Filter messages by specific contacts or phone numbers
• Fuzzy Search: Search through message content with intelligent matching
• iMessage Detection: Check if recipients have iMessage before sending
• Cross-Platform: Works with both iPhone/Mac users (iMessage) and Android users (SMS/RCS)

Prerequisites

• macOS (tested on macOS 11+)
• Python 3.10+
• uv package manager

Installing uv

If you're on Mac, install uv using Homebrew:

brew install uv

Otherwise, follow the installation instructions on the uv website.

⚠️ Do not proceed before installing uv

Installation

Full Disk Access Permission

⚠️ This application requires Full Disk Access permission for your terminal or application to access the Messages database.

To grant Full Disk Access:

1. Open System Preferences/Settings > Security & Privacy/Privacy > Full Disk Access
2. Click the lock icon to make changes
3. Add your terminal app (Terminal, iTerm2, etc.) or Claude Desktop/Cursor to the list
4. Restart your terminal or application after granting permission

Integration

Claude Desktop Integration

1. Go to Claude > Settings > Developer > Edit Config > claude_desktop_config.json
2. Add the following configuration:

{
    "mcpServers": {
        "messages": {
            "command": "uvx",
            "args": [
                "mac-messages-mcp"
            ]
        }
    }
}

Cursor Integration

Option 1: One-Click Install (Recommended)

Option 2: Manual Setup

Go to Cursor Settings > MCP and paste this as a command:

uvx mac-messages-mcp

⚠️ Only run one instance of the MCP server (either on Cursor or Claude Desktop), not both

Option 1: Install from PyPI

uv pip install mac-messages-mcp

Option 2: Install from source

# Clone the repository
git clone https://github.com/carterlasalle/mac_messages_mcp.git
cd mac_messages_mcp

# Install dependencies
uv install -e .

Usage

Smart Message Delivery

Mac Messages MCP automatically handles message delivery across different platforms:

• iMessage Users (iPhone, iPad, Mac): Messages sent via iMessage
• Android Users: Messages automatically fall back to SMS/RCS
• Mixed Groups: Optimal delivery method chosen per recipient

# Send to iPhone user - uses iMessage
send_message("+1234567890", "Hey! This goes via iMessage")

# Send to Android user - automatically uses SMS
send_message("+1987654321", "Hey! This goes via SMS") 

# Check delivery method before sending
check_imessage_availability("+1234567890")  # Returns availability status

As a Module

from mac_messages_mcp import get_recent_messages, send_message

# Get recent messages
messages = get_recent_messages(hours=48)
print(messages)

# Send a message (automatically chooses iMessage or SMS)
result = send_message(recipient="+1234567890", message="Hello from Mac Messages MCP!")
print(result)  # Shows whether sent via iMessage or SMS

As a Command-Line Tool

# Run the MCP server directly
mac-messages-mcp

Development

Versioning

This project uses semantic versioning. See VERSIONING.md for details on how the versioning system works and how to release new versions.

To bump the version:

python scripts/bump_version.py [patch|minor|major]

Security Notes

This application accesses the Messages database directly, which contains personal communications. Please use it responsibly and ensure you have appropriate permissions.

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Star History