Mac Messages MCP
A Python bridge for interacting with the macOS Messages app using MCP (Multiple Context Protocol).
Quick Install
For Cursor Users
Click the button above to automatically add Mac Messages MCP to Cursor
For Claude Desktop Users
See the Integration section below for setup instructions.
Features
- Universal Message Sending: Automatically sends via iMessage or SMS/RCS based on recipient availability
- Smart Fallback: Seamless fallback to SMS when iMessage is unavailable (perfect for Android users)
- Message Reading: Read recent messages from the macOS Messages app
- Contact Filtering: Filter messages by specific contacts or phone numbers
- Fuzzy Search: Search through message content with intelligent matching
- iMessage Detection: Check if recipients have iMessage before sending
- Cross-Platform: Works with both iPhone/Mac users (iMessage) and Android users (SMS/RCS)
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
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:
{
"mcpServers": {
"messages": {
"command": "uvx",
"args": [
"mac-messages-mcp"
]
}
}
}
Cursor Integration
Option 1: One-Click Install (Recommended)
Option 2: Manual Setup
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
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
Smart Message Delivery
Mac Messages MCP automatically handles message delivery across different platforms:
- iMessage Users (iPhone, iPad, Mac): Messages sent via iMessage
- Android Users: Messages automatically fall back to SMS/RCS
- Mixed Groups: Optimal delivery method chosen per recipient
# Send to iPhone user - uses iMessage
send_message("+1234567890", "Hey! This goes via iMessage")
# Send to Android user - automatically uses SMS
send_message("+1987654321", "Hey! This goes via SMS")
# Check delivery method before sending
check_imessage_availability("+1234567890") # Returns availability status
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 (automatically chooses iMessage or SMS)
result = send_message(recipient="+1234567890", message="Hello from Mac Messages MCP!")
print(result) # Shows whether sent via iMessage or SMS
As a Command-Line Tool
# Run the MCP server directly
mac-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:
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.
Star History
