An MCP server that securely interfaces with your iMessage database via the Model Context Protocol (MCP), allowing LLMs to query and analyze iMessage conversations. It includes robust phone number validation, attachment processing, contact management, group chat handling, and full support for sending and receiving messages.
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:
1brew 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:
- Open System Preferences/Settings > Security & Privacy/Privacy > Full Disk Access
- Click the lock icon to make changes
- Add your terminal app (Terminal, iTerm2, etc.) or Claude Desktop/Cursor to the list
- Restart your terminal or application after granting permission
Integration
Claude Desktop Integration
- Go to Claude > Settings > Developer > Edit Config > claude_desktop_config.json
- Add the following configuration:
1{ 2 "mcpServers": { 3 "messages": { 4 "command": "uvx", 5 "args": [ 6 "mac-messages-mcp" 7 ] 8 } 9 } 10}
Cursor Integration
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
1uv pip install mac-messages-mcp
Option 2: Install from source
1# Clone the repository 2git clone https://github.com/carterlasalle/mac_messages_mcp.git 3cd mac_messages_mcp 4 5# Install dependencies 6uv install -e .
Usage
As a Module
1from mac_messages_mcp import get_recent_messages, send_message 2 3# Get recent messages 4messages = get_recent_messages(hours=48) 5print(messages) 6 7# Send a message 8result = send_message(recipient="+1234567890", message="Hello from Mac Messages MCP!") 9print(result)
As a Command-Line Tool
1# Run the MCP server directly 2mac-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:
1python 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.