Mac Messages MCP

🚀 macOS Messages MCP Read-Write Bridge (Python Version)

A Python bridge for interacting with the macOS Messages application via MCP (Multi-Context Protocol).

🚀 Quick Start

This is a Python bridge that enables interaction with the macOS Messages application through the MCP (Multi-Context Protocol). It allows users to read recent messages, filter messages by contact, send new messages via iMessage, and access messages through an API.

✨ Features

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

📦 Installation

Prerequisites

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

Install uv

If you're using a Mac, install uv via Homebrew:

brew install uv

Otherwise, follow the installation instructions on the uv official website.

⚠️ Important Note

Do not proceed until you have installed uv.

Full Disk Access Permission

⚠️ Important Note

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

Steps to set up Full Disk Access:

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

Installation Options

Option 1: Install from PyPI

uv pip install mac-messages-mcp

Option 2: Install from source code

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

# Install dependencies
uv install -e .

💻 Usage Examples

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

Use as a command-line tool

# Run the MCP server
mac-messages-mcp

📚 Documentation

Integration

Claude Desktop Integration

1. Go to Claude > Settings > Developer > Edit Configuration > 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 the following command:

uvx mac-messages-mcp

⚠️ Important Note

Only one instance of the MCP server can be run (either for Claude Desktop or Cursor). Do not run both simultaneously.

Development

Version Control

This project uses semantic versioning. For details on how the version control system works and how to release new versions, refer to VERSIONING.md.

To adjust the version:

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

Security Considerations

This application directly accesses the Messages database. Proper management of permissions and data security is required.

Additional Notes

Introduction to the MCP Protocol

MCP (Multi-Context Protocol) is a mechanism for communication between different processes or services. In this project, we use MCP to bridge the interaction between Python scripts and the macOS Messages application.

Supported Message Operations

Currently, the following message-related operations are supported:

• Get recent messages.
• Filter messages by contact.
• Send new messages.

Future Development

Future plans include adding more features, such as:

• Support for more message types.
• Providing a graphical user interface.
• Enhancing security and stability.

Contributors

This project is developed and maintained by carterlasalle.

📄 License

This project is licensed under the MIT License.