Seamless iMessage Integration: mac-messages-mcp - A Robust MCP Server for macOS Messages

Harness the power of the Model Context Protocol (MCP) to bridge the gap between your Large Language Model (LLM) applications and the rich communication history of macOS Messages. mac-messages-mcp provides a streamlined, secure, and efficient way to access and interact with iMessage directly from your AI workflows.

Key Capabilities

• Read Recent Messages: Effortlessly retrieve recent message history from the macOS Messages database.
• Contact-Specific Filtering: Precisely target message retrieval by filtering based on specific contacts.
• Programmatic Message Sending: Initiate new iMessage conversations or respond to existing threads directly through the API.
• MCP-Compliant API: Seamlessly integrate with any LLM application that supports the Model Context Protocol.

Prerequisites: Setting the Stage for Success

• macOS Compatibility: Rigorously tested and optimized for macOS 11 and later.
• Python Environment: Requires Python 3.10 or higher.
• uv Package Manager: Leverages the speed and efficiency of the uv package manager for dependency management.

Installing uv: The Modern Package Manager

For macOS users, the recommended installation method is via Homebrew:

brew install uv

Alternatively, consult the official uv website for comprehensive installation instructions tailored to your specific environment.

⚠️ Crucially, ensure uv is correctly installed before proceeding.

Installation: Bringing mac-messages-mcp to Life

Granting Full Disk Access: A Security Imperative

⚠️ Full Disk Access permission is mandatory for your terminal or application to interact with the Messages database. This is a critical security consideration.

To grant Full Disk Access:

1. Navigate to System Preferences/Settings > Security & Privacy/Privacy > Full Disk Access.
2. Click the lock icon to enable changes.
3. Add your terminal application (e.g., Terminal, iTerm2) or the application you're integrating with (e.g., Claude Desktop, Cursor) to the list.
4. Restart your terminal or application after granting the necessary permissions.

Integration with LLM Platforms: Claude Desktop & Cursor

Claude Desktop Configuration

1. Access the configuration file: Claude > Settings > Developer > Edit Config > claude_desktop_config.json.
2. Append the following JSON snippet to configure the MCP server:

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

Cursor Configuration

Within Cursor's settings, locate the MCP configuration section and specify the following command:

uvx mac-messages-mcp

⚠️ Important: Avoid running multiple instances of the MCP server simultaneously across different platforms (e.g., both Cursor and Claude Desktop).

Installation Options: Choose Your Path

Option 1: Installation via PyPI (Recommended)

Leverage the Python Package Index for a streamlined installation:

uv pip install mac-messages-mcp

Option 2: Installation from Source (For Development)

For developers and contributors, installation from source offers greater flexibility:

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

# Install dependencies
uv install -e .

Usage: Unleashing the Power of mac-messages-mcp

As a Python Module: Fine-Grained Control

from mac_messages_mcp import get_recent_messages, send_message

# Retrieve recent messages from the past 48 hours
messages = get_recent_messages(hours=48)
print(messages)

# Send a message to a specific recipient
result = send_message(recipient="+1234567890", message="Hello from Mac Messages MCP!")
print(result)

As a Command-Line Tool: Direct MCP Server Execution

# Start the MCP server directly
mac-messages-mcp

Development: Contributing to the Future

Versioning Strategy

This project adheres to semantic versioning principles. Refer to VERSIONING.md for a detailed explanation of the versioning scheme and the release process.

To increment the version number:

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

Security Considerations: Prioritizing User Privacy

This application directly interacts with the Messages database, which contains sensitive personal communication data. Exercise responsible usage and ensure adherence to all applicable privacy regulations and ethical guidelines.

Contributing: Shaping the Project's Evolution

We welcome contributions from the community! Please submit pull requests to contribute enhancements, bug fixes, or new features.