Mac Messages MCP Server

CommunicationPython

Access and interact with macOS Messages app

Available Tools

get_recent_messages

Retrieves recent messages from the macOS Messages app, with options to filter by contact and time period.

hourscontact_namephone_numberlimit

search_messages

Searches through message history for specific text or from specific contacts.

querycontact_namephone_numberlimit

send_message

Sends a new message through iMessage to a specified recipient.

recipientmessage

find_contact

Searches for contact information based on name or phone number.

query

Mac Messages MCP provides a secure bridge for AI assistants to interact with your macOS Messages app. It enables reading recent conversations, searching through message history, managing contacts, and sending new messages directly through iMessage, all while maintaining privacy and security.

Overview

Mac Messages MCP creates a secure interface between AI assistants and your macOS Messages app, allowing for seamless interaction with your iMessage conversations. This tool enables you to read recent messages, search through conversation history, manage contacts, and send new messages directly through iMessage.

Prerequisites

Before installing Mac Messages MCP, ensure you have:

macOS (tested on macOS 11+)
Python 3.10 or newer
The uv package manager installed

Installing uv Package Manager

The Mac Messages MCP requires the uv package manager. Install it using Homebrew:

brew install uv

If you're not using macOS or prefer another installation method, follow the instructions on the uv GitHub repository.

Installation

You can install Mac Messages MCP directly from PyPI:

uv pip install mac-messages-mcp

Alternatively, you can install from source:

git clone https://github.com/carterlasalle/mac_messages_mcp.git
cd mac_messages_mcp
uv install -e .

Required Permissions

⚠️ Important: Mac Messages MCP requires Full Disk Access permission to access the Messages database.

To grant this permission:

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

Without this permission, the MCP will not be able to access your messages.

Integration with AI Assistants

Claude Desktop Integration

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

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

Cursor Integration

Go to Cursor Settings > MCP
Add a new MCP server with the command:

uvx mac-messages-mcp

⚠️ Note: Only run one instance of the MCP server at a time (either on Cursor or Claude Desktop, not both).

Usage

Once installed and configured, the AI assistant can interact with your Messages app through the available tools. The assistant can:

Retrieve recent messages from specific contacts or conversations
Search through message history
Send new messages to contacts
Look up contact information

The MCP handles all the necessary database interactions and ensures secure access to your messages.

Troubleshooting

If you encounter issues:

Verify that Full Disk Access permission has been granted
Ensure only one instance of the MCP server is running
Check that you're using the correct version of Python (3.10+)
Restart your terminal or AI application after making configuration changes

For further assistance, visit the GitHub repository.