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.
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
Docker Container Integration
If you need to connect to mac-messages-mcp from a Docker container, you'll need to use the mcp-proxy package to bridge the stdio-based server to HTTP.
Setup Instructions
Install mcp-proxy on your macOS host:
npm install -g mcp-proxy
Start the proxy server:
# Using the published version
npx mcp-proxy uvx mac-messages-mcp --port 8000 --host 0.0.0.0
# Or using local development (if you encounter issues)
npx mcp-proxy uv run python -m mac_messages_mcp.server --port 8000 --host 0.0.0.0
Connect from Docker:
Your Docker container can now connect to:
URL: http://host.docker.internal:8000/mcp (on macOS/Windows)
URL: http://<host-ip>:8000/mcp (on Linux)
Docker Compose example:
version: '3.8'
services:
your-app:
image: your-image
environment:
MCP_MESSAGES_URL: "http://host.docker.internal:8000/mcp"
extra_hosts:
- "host.docker.internal:host-gateway" # For Linux hosts
Running multiple MCP servers:
# Terminal 1 - Messages MCP on port 8001
npx mcp-proxy uvx mac-messages-mcp --port 8001 --host 0.0.0.0
# Terminal 2 - Another MCP server on port 8002
npx mcp-proxy uvx another-mcp-server --port 8002 --host 0.0.0.0
Note: Binding to 0.0.0.0 exposes the service to all network interfaces. In production, consider using more restrictive host bindings and adding authentication.
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.
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.
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
