📌Overview

Purpose: To provide a Python bridge for seamless interaction with the macOS Messages app using the Multiple Context Protocol (MCP).

Overview: Mac Messages MCP is a powerful framework designed for developers to easily access and manage messages within the macOS Messages app. It allows for reading, filtering, and sending messages programmatically, enhancing automation and integration possibilities.

Key Features:

• Read Recent Messages: Enables users to retrieve recent messages from the Messages app, facilitating analysis and tracking of conversations.

• Filter Messages by Contact: Offers the ability to filter messages based on specific contacts, allowing targeted communication management.

• Send New Messages: Provides the functionality to send messages via iMessage, streamlining communication processes directly from scripts or applications.

• Access Messages via an API: Allows developers to integrate messaging capabilities into their applications through a well-defined API, promoting flexibility and extensibility.

---

Mac Messages MCP

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

Features

• Read recent messages from the macOS Messages app
• Filter messages by contact
• Send new messages through iMessage
• Access messages via an API

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

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 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

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

uvx mac-messages-mcp

Installation Methods

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

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
result = send_message(recipient="+1234567890", message="Hello from Mac Messages MCP!")
print(result)

As a Command-Line Tool

# Run the MCP server directly
mac-messages-mcp

Development

Versioning

This project uses semantic versioning. 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.