A
securityA
licenseA
qualityEnables interaction with Apple apps like Messages, Notes, and Contacts through the MCP protocol to send messages, search, and open app content using natural language.
Last updated -
4
7
150
2,816
MIT License
The Mac Messages MCP server allows interaction with the macOS Messages app, enabling users to:
Retrieve Recent Messages: Fetch messages with optional filtering by contact or time range
Send Messages: Send to individuals (via phone number, email, or contact name) or group chats (using chat ID)
Find Contacts: Search for contacts by name using fuzzy matching
List Contacts: Retrieve available contacts from the address book
List Group Chats: Get available group chats in the Messages app
Diagnose Access Issues: Check for and troubleshoot database and AddressBook access problems
API Integration: Integrate with tools like Claude Desktop or Cursor for messaging workflows
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
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
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
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. 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
Related MCP Servers
- -securityAlicense-qualityA macOS app that provides an MCP server to your Messages, Contacts, and moreLast updated -947MIT License
- -security-license-qualityA collection of Apple-native tools for the MCP protocol that enables AI assistants to interact with Apple applications including Messages, Notes, Contacts, Mail, Reminders, Calendar, and Maps.
- -security-license-qualityA Python-based MCP server that uses uv for dependency management, requiring Python 3.13+ to run.